{"id":28906835,"url":"https://github.com/i2y/mcpizer","last_synced_at":"2026-04-27T16:32:04.263Z","repository":{"id":299816326,"uuid":"1002696731","full_name":"i2y/mcpizer","owner":"i2y","description":"Convert any REST API or gRPC service into MCP tools for AI assistants","archived":false,"fork":false,"pushed_at":"2025-06-21T12:00:36.000Z","size":171,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T02:41:43.174Z","etag":null,"topics":["api-bridge","go","grpc","mcp","model-context-protocol","openapi"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/i2y.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-16T02:03:44.000Z","updated_at":"2025-06-21T12:00:39.000Z","dependencies_parsed_at":"2025-06-18T13:25:27.727Z","dependency_job_id":"8884caf6-7f33-4b24-a004-3e387d3c1b3f","html_url":"https://github.com/i2y/mcpizer","commit_stats":null,"previous_names":["i2y/mcpizer"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/i2y/mcpizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fmcpizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fmcpizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fmcpizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fmcpizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/i2y","download_url":"https://codeload.github.com/i2y/mcpizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/i2y%2Fmcpizer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32345802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-bridge","go","grpc","mcp","model-context-protocol","openapi"],"created_at":"2025-06-21T15:10:02.328Z","updated_at":"2026-04-27T16:32:04.247Z","avatar_url":"https://github.com/i2y.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCPizer\n\nMCPizer lets your AI assistant (Claude, VS Code, etc.) call any REST API or gRPC service by automatically converting their schemas into MCP (Model Context Protocol) tools.\n\n**Key Features:** \n- 🚀 GitHub integration - fetch schemas directly with `github://` URLs\n- 📄 .proto file support - use gRPC without reflection enabled\n- 🔐 Private repo support - automatic authentication via `gh` CLI\n- 🌐 Connect-RPC support - HTTP/JSON and gRPC modes\n- 🔧 Auto-discovery - finds OpenAPI/Swagger endpoints automatically\n\n## What is MCPizer?\n\nMCPizer is a server that:\n- **Auto-discovers** API schemas from your services (OpenAPI/Swagger, gRPC reflection, .proto files)\n- **Converts** them into tools your AI can use\n- **Handles** all the API calls with proper types and error handling\n\nWorks with any framework that exposes OpenAPI schemas (FastAPI, Spring Boot, Express, etc.) or gRPC services (with reflection or .proto files). No code changes needed in your APIs - just point MCPizer at them!\n\n## How it Works\n\n```mermaid\nsequenceDiagram\n    participant AI as AI Assistant\u003cbr/\u003e(Claude/VS Code)\n    participant MCP as MCPizer\n    participant API as Your APIs\u003cbr/\u003e(REST/gRPC)\n    \n    Note over AI,API: Initial Setup\n    MCP-\u003e\u003eAPI: Auto-discover schemas\n    API--\u003e\u003eMCP: OpenAPI/gRPC reflection\n    MCP-\u003e\u003eMCP: Convert to MCP tools\n    \n    Note over AI,API: Runtime Usage\n    AI-\u003e\u003eMCP: List available tools\n    MCP--\u003e\u003eAI: Tools from all APIs\n    AI-\u003e\u003eMCP: Call tool \"create_user\"\n    MCP-\u003e\u003eAPI: POST /users\n    API--\u003e\u003eMCP: {\"id\": 123, \"name\": \"Alice\"}\n    MCP--\u003e\u003eAI: Tool result\n```\n\n### Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"AI Assistants\"\n        Claude[Claude Desktop]\n        VSCode[VS Code Extensions]\n        Other[Other MCP Clients]\n    end\n    \n    subgraph \"MCPizer\"\n        Transport{Transport Layer}\n        Discovery[Schema Discovery]\n        Converter[Tool Converter]\n        Invoker[API Invoker]\n        \n        Transport --\u003e|STDIO/SSE| Discovery\n        Discovery --\u003e Converter\n        Converter --\u003e Invoker\n    end\n    \n    subgraph \"Your APIs\"\n        FastAPI[FastAPI\u003cbr/\u003eAuto-discovery]\n        Spring[Spring Boot\u003cbr/\u003eAuto-discovery]\n        gRPC[gRPC Services\u003cbr/\u003eReflection/.proto]\n        Custom[Custom APIs\u003cbr/\u003eDirect schema URL]\n    end\n    \n    Claude --\u003e Transport\n    VSCode --\u003e Transport\n    Other --\u003e Transport\n    \n    Invoker --\u003e FastAPI\n    Invoker --\u003e Spring\n    Invoker --\u003e gRPC\n    Invoker --\u003e Custom\n    \n    style MCPizer fill:#e1f5e1\n    style Transport fill:#fff2cc\n    style Discovery fill:#fff2cc\n    style Converter fill:#fff2cc\n    style Invoker fill:#fff2cc\n```\n\n## Installation\n\n```bash\n# Install MCPizer\ngo install github.com/i2y/mcpizer/cmd/mcpizer@latest\n\n# Verify installation\nmcpizer --help\n```\n\n### Usage Examples\n\n```bash\n# Use default config file (configs/mcpizer.yaml)\nmcpizer\n\n# Specify config file via command line (highest priority)\nmcpizer -config=/path/to/config.yaml\n\n# Use GitHub-hosted config\nmcpizer -config=github://myorg/configs/mcpizer-prod.yaml\n\n# Or via environment variable\nexport MCPIZER_CONFIG_FILE=/path/to/config.yaml\nmcpizer\n\n# STDIO mode with custom config\nmcpizer -transport=stdio -config=./my-config.yaml\n```\n\n\u003e **Note**: Make sure `$GOPATH/bin` is in your PATH. If not installed, [install Go first](https://golang.org/doc/install).\n\n## Quick Start\n\n### Step 1: Configure Your APIs\n\nCreate a config file with your API endpoints:\n\n```yaml\nschema_sources:\n  # Production APIs with HTTPS\n  - https://api.mycompany.com              # Auto-discovers OpenAPI\n  - https://api.example.com/openapi.json   # Direct schema URL\n  \n  # GitHub-hosted schemas (NEW: use github:// URLs)\n  - github://myorg/api-specs/main/user-api.yaml     # Uses gh CLI auth\n  - github://OAI/OpenAPI-Specification/examples/v3.0/petstore.yaml@master\n  - https://raw.githubusercontent.com/myorg/api-specs/main/user-api.yaml  # Direct URL also works\n  \n  # Internal services (FastAPI, Spring Boot, etc.)\n  - http://my-fastapi-app:8000     # Auto-discovers at /openapi.json, /docs\n  - http://spring-service:8080     # Auto-discovers at /v3/api-docs\n  \n  # gRPC services (must have reflection enabled)\n  - grpc://my-grpc-service:50051\n  \n  # gRPC with .proto files (NEW! - no reflection needed)\n  - url: https://raw.githubusercontent.com/myorg/protos/main/service.proto\n    server: grpc://production.example.com:50051\n  \n  # Or use github:// for private repos (uses gh CLI)\n  - url: github://myorg/protos/service.proto@main\n    server: grpc://production.example.com:50051\n  \n  # Connect-RPC services (NEW!)\n  # If the service supports gRPC reflection:\n  - grpc://connect.example.com:50051\n  \n  # Connect-RPC with HTTP/JSON mode:\n  - url: github://connectrpc/examples/eliza/eliza.proto\n    server: https://demo.connectrpc.com\n    type: connect\n    mode: http  # Use HTTP/JSON for easier debugging\n  \n  # Local development\n  - http://localhost:3000\n  - grpc://localhost:50052\n  \n  # Public test APIs\n  - https://petstore3.swagger.io/api/v3/openapi.json\n  - grpc://grpcb.in:9000\n```\n\n### Step 2: Choose Your Transport Mode\n\nMCPizer supports two transport modes:\n\n#### 📝 **STDIO Mode** (for clients that manage process lifecycle)\n\nUsed by clients that start MCPizer as a subprocess and communicate via standard input/output.\n\n**Example: Claude Desktop**\n\nAdd to your configuration file:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpizer\": {\n      \"command\": \"mcpizer\",\n      \"args\": [\"-transport=stdio\", \"-config=/path/to/your/config.yaml\"]\n    }\n  }\n}\n```\n\nThe client will start MCPizer automatically when needed.\n\n#### 🌐 **SSE Mode** (Server-Sent Events over HTTP)\n\nUsed by clients that connect to a running MCPizer server via HTTP.\n\n```bash\n# Start MCPizer server (if your client doesn't start it automatically)\nmcpizer\n\n# Server runs at http://localhost:8080/sse\n```\n\nConfigure your MCP client to connect to `http://localhost:8080/sse`\n\nNote: Some clients may start the server automatically, while others require manual startup.\n\n#### 🧪 **For Testing/Development**\n\n```bash\n# Quick test - list available tools\nmcpizer -transport=stdio \u003c\u003c 'EOF'\n{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}\nEOF\n\n# Interactive mode\nmcpizer -transport=stdio\n```\n\n## Usage Guide\n\n### When to Use What\n\n| I want to... | Do this... |\n|--------------|------------|\n| Use my API with Claude Desktop | Add config to `claude_desktop_config.json` (see Quick Start) |\n| Test if my API works with MCP | Run `mcpizer -transport=stdio` and check tool list |\n| Run as a background service | Use SSE mode with `mcpizer` (no args) |\n| Debug connection issues | Set `MCPIZER_LOG_LEVEL=debug` |\n| Use a private GitHub repo | Use `github://` URLs (requires `gh` CLI) |\n| Use gRPC without reflection | Use .proto files with `server` field |\n| Multiple environments, same API | Use same schema file, different `server` values |\n\n### Configuration\n\nMCPizer looks for config in this order:\n1. `-config` command line flag (highest priority)\n2. `$MCPIZER_CONFIG_FILE` environment variable\n3. `configs/mcpizer.yaml` (default)\n\n#### Supported API Types\n\n**REST APIs (OpenAPI/Swagger)**\n```yaml\nschema_sources:\n  # Auto-discovery from base URL\n  - https://api.production.com      # Tries /openapi.json, /swagger.json, etc.\n  - http://internal-api:8000        # For internal services\n  \n  # Direct schema URLs\n  - https://api.example.com/v3/openapi.yaml\n  - https://raw.githubusercontent.com/company/api-specs/main/openapi.json\n```\n\n**Connect-RPC Services (NEW!)**\n```yaml\nschema_sources:\n  # Connect-RPC with gRPC reflection (if supported)\n  - grpc://connect.example.com:50051\n  \n  # Connect-RPC with HTTP/JSON mode\n  - url: github://connectrpc/examples/eliza/eliza.proto\n    server: https://demo.connectrpc.com\n    type: connect\n    mode: http    # HTTP/JSON mode (default)\n  \n  # Connect-RPC with gRPC mode\n  - url: https://raw.githubusercontent.com/myorg/protos/service.proto\n    server: grpc://connect.example.com:50051\n    type: connect\n    mode: grpc    # Use gRPC transport\n```\n\nConnect-RPC features:\n- **HTTP/JSON mode**: Human-readable, works with curl and browser tools\n- **gRPC mode**: Binary protocol, more efficient\n- **Dual support**: Same service can be accessed via both modes\n- **No proxy needed**: Direct HTTP/JSON communication\n\n### Separate Schema Files and API Servers\n\nMCPizer supports OpenAPI schema files that are hosted separately from the actual API server. This is useful when:\n\n1. **The API doesn't expose its own schema** - You can write an OpenAPI spec for any API\n2. **Schema is managed separately** - Documentation team maintains schemas independently\n3. **Multiple environments** - One schema file for dev/staging/production APIs\n\n**How it works:**\n```yaml\nschema_sources:\n  # Schema file points to production API\n  - https://docs.company.com/api/v1/openapi.yaml\n  \n  # Local schema file for external API\n  - ./schemas/third-party-api.yaml\n```\n\nThe OpenAPI spec contains server URLs:\n```yaml\nservers:\n  - url: https://api.production.com\n    description: Production server\n  - url: https://api.staging.com\n    description: Staging server\n```\n\nMCPizer will:\n1. Fetch the schema from the schema_sources URL\n2. Read the `servers` section from the OpenAPI spec\n3. Use the first available server URL for actual API calls\n\n**Example: Creating OpenAPI spec for an API without documentation**\n\nIf you have an API at `https://internal-api.company.com` that doesn't provide OpenAPI:\n\n1. Write your own OpenAPI spec:\n```yaml\nopenapi: 3.0.0\ninfo:\n  title: Internal API\n  version: 1.0.0\nservers:\n  - url: https://internal-api.company.com\npaths:\n  /users:\n    get:\n      summary: List users\n      responses:\n        '200':\n          description: Success\n          content:\n            application/json:\n              schema:\n                type: array\n                items:\n                  type: object\n                  properties:\n                    id: {type: integer}\n                    name: {type: string}\n```\n\n2. Host it anywhere:\n   - GitHub: `https://raw.githubusercontent.com/yourorg/specs/main/api.yaml`\n   - S3/CDN: `https://cdn.company.com/api-specs/v1/openapi.json`\n   - Local file: `./schemas/third-party-api.yaml`\n3. Point MCPizer to your schema file\n\n### Auto-Discovery Process\n\n```mermaid\ngraph TD\n    Start[\"Base URL provided:\u003cbr/\u003ehttp://your-api:8000\"] \n    \n    Try1[\"/openapi.json\u003cbr/\u003eFastAPI default\"]\n    Try2[\"/docs/openapi.json\u003cbr/\u003eFastAPI alt\"]\n    Try3[\"/swagger.json\u003cbr/\u003eSwagger 2.0\"]\n    Try4[\"/v3/api-docs\u003cbr/\u003eSpring Boot\"]\n    Try5[\"...more paths...\"]\n    \n    Found[\"✓ Schema found!\u003cbr/\u003eParse and convert\"]\n    NotFound[\"✗ Not found\u003cbr/\u003eTry direct URL\"]\n    \n    Start --\u003e Try1\n    Try1 --\u003e|404| Try2\n    Try2 --\u003e|404| Try3\n    Try3 --\u003e|404| Try4\n    Try4 --\u003e|404| Try5\n    \n    Try1 --\u003e|200| Found\n    Try2 --\u003e|200| Found\n    Try3 --\u003e|200| Found\n    Try4 --\u003e|200| Found\n    \n    Try5 --\u003e|All fail| NotFound\n    \n    style Start fill:#e3f2fd\n    style Found fill:#c8e6c9\n    style NotFound fill:#ffcdd2\n```\n\nSupported frameworks:\n- **FastAPI**: `/openapi.json`, `/docs/openapi.json`\n- **Spring Boot**: `/v3/api-docs`, `/swagger-ui/swagger.json`  \n- **Express/NestJS**: `/api-docs`, `/swagger.json`\n- **Rails**: `/api/v1/swagger.json`, `/apidocs`\n- [See full list](internal/adapter/outbound/openapi/autodiscover.go)\n\n**gRPC Services**\n```yaml\nschema_sources:\n  # Using gRPC reflection (requires reflection enabled on server)\n  - grpc://your-grpc-host:50051     # Your service\n  - grpc://grpcb.in:9000            # Public test service\n  \n  # Using .proto files (NEW! - no reflection needed)\n  - url: https://raw.githubusercontent.com/grpc/grpc-go/master/examples/helloworld/helloworld/helloworld.proto\n    server: grpc://production.example.com:50051\n  \n  # Private GitHub .proto files (uses gh CLI authentication)\n  - url: github://myorg/protos/user-service.proto\n    server: grpc://user-service:50051\n  \n  # With specific branch/tag\n  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@v1.65.0\n    server: grpc://production.example.com:50051\n```\n\n**Option 1: gRPC Reflection** (requires [reflection](https://github.com/grpc/grpc/blob/master/doc/server-reflection.md) enabled):\n```go\n// In your gRPC server\nimport \"google.golang.org/grpc/reflection\"\nreflection.Register(grpcServer)\n```\n\n**Option 2: .proto Files** (NEW! - more secure, no reflection needed):\n- Host your `.proto` files anywhere (GitHub, S3, CDN, etc.)\n- GitHub URLs (`github://`) automatically use `gh` CLI authentication\n- Specify the `server` endpoint separately\n- Perfect for production where reflection is disabled\n- Allows schema versioning and CI/CD validation\n\nFor alternative reflection implementations, see:\n- [connectrpc/grpcreflect-go](https://github.com/connectrpc/grpcreflect-go)  Connect-Go's reflection implementation\n\n**Local Files**\n```yaml\nschema_sources:\n  - ./api-spec.json\n  - /path/to/openapi.yaml\n```\n\n### GitHub Integration (NEW!)\n\nMCPizer can fetch schemas directly from GitHub repositories using the `gh` CLI tool - including both OpenAPI and .proto files:\n\n```yaml\nschema_sources:\n  # OpenAPI schemas from GitHub\n  - github://owner/repo/path/to/openapi.yaml\n  - github://microsoft/api-guidelines/graph/openapi.yaml@v1.0\n  \n  # .proto files from GitHub (NEW!)\n  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@master\n    server: grpc://production.example.com:50051\n  \n  # Private repositories (uses gh CLI authentication)\n  - github://myorg/private-apis/user-api.yaml\n  - url: github://myorg/private-protos/service.proto@v2.0\n    server: grpc://internal-service:50051\n  \n  # Load MCPizer config itself from GitHub!\n  # Set MCPIZER_CONFIG_FILE=github://myorg/configs/mcpizer.yaml\n```\n\n**Benefits:**\n- ✅ Works with private repositories (uses `gh` authentication)\n- ✅ Specify branches/tags with `@ref` syntax\n- ✅ No need to manage raw GitHub URLs or tokens\n- ✅ Supports both OpenAPI and .proto files\n- ✅ Config files can also be stored in GitHub\n\n**Requirements:**\n- Install GitHub CLI: `brew install gh` (macOS) or [see docs](https://cli.github.com/)\n- Authenticate: `gh auth login`\n\n### Environment Variables\n\n| Variable | Default | When to use |\n|----------|---------|-------------|\n| `MCPIZER_CONFIG_FILE` | `~/.mcpizer.yaml` | Different config per environment\u003cbr/\u003eCan be `github://` URL! |\n| `MCPIZER_LOG_LEVEL` | `info` | Set to `debug` for troubleshooting |\n| `MCPIZER_LOG_FILE` | `/tmp/mcpizer.log` | Change log location (STDIO mode) |\n| `MCPIZER_LISTEN_ADDR` | `:8080` | Change port (SSE mode) |\n| `MCPIZER_HTTP_CLIENT_TIMEOUT` | `30s` | Slow APIs need more time |\n\n## Common Scenarios\n\n### \"I want Claude to use my local FastAPI app\"\n\n```bash\n# 1. Your FastAPI runs on port 8000\npython -m uvicorn main:app\n\n# 2. Install MCPizer\ngo install github.com/i2y/mcpizer/cmd/mcpizer@latest\n\n# 3. Configure (~/.mcpizer.yaml)\necho \"schema_sources:\\n  - http://localhost:8000\" \u003e ~/.mcpizer.yaml\n\n# 4. Add to Claude Desktop config and restart\n# Now ask Claude: \"What endpoints are available?\"\n```\n\n### \"I want to test if MCPizer sees my API\"\n\n```bash\n# Quick check - what tools are available?\nmcpizer -transport=stdio \u003c\u003c 'EOF'\n{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}\nEOF\n\n# Should list all your API endpoints as tools\n```\n\n### \"My API needs authentication\"\n\n```yaml\n# For APIs that require authentication headers\nschema_sources:\n  # Object format with headers (for fetching schemas)\n  - url: https://api.example.com/openapi.json\n    headers:\n      Authorization: \"Bearer YOUR_API_TOKEN\"\n      X-API-Key: \"YOUR_API_KEY\"\n  \n  # GitHub private repos (automatic auth via gh CLI)\n  - github://myorg/private-apis/openapi.yaml     # No headers needed!\n  - url: github://myorg/private-protos/api.proto  # gh handles auth\n    server: grpc://api.example.com:50051\n  \n  # Simple format (no auth required)\n  - https://public-api.example.com/swagger.json\n```\n\nNote: These headers are used when fetching the schema files. Headers required for actual API calls should be defined in the OpenAPI spec itself.\n\n### \"I'm getting 'no tools available'\"\n\n```bash\n# 1. Check if your API is running\ncurl http://localhost:8000/openapi.json  # Should return JSON\n\n# 2. Run with debug logging\nMCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio\n\n# 3. Check the log file\ntail -f /tmp/mcpizer.log\n```\n\n### \"I want to use my company's gRPC services\"\n\n**Option 1: If reflection is enabled**\n```yaml\n# Simple - just point to the service\nschema_sources:\n  - grpc://my-service:50051\n```\n\n**Option 2: Using .proto files (recommended)**\n```yaml\n# More secure - no reflection needed in production\nschema_sources:\n  # From GitHub (private repos supported)\n  - url: github://mycompany/protos/user-service.proto@v1.0.0\n    server: grpc://user-service.prod:443\n  \n  # From any HTTPS URL\n  - url: https://cdn.mycompany.com/schemas/order-service.proto\n    server: grpc://order-service.prod:443\n```\n\n### \"I want to run MCPizer as a service\"\n\n**Option 1: Direct binary execution**\n```bash\n# Run in background with specific config\nmcpizer -config /etc/mcpizer/production.yaml \u0026\n\n# Or use systemd (create /etc/systemd/system/mcpizer.service)\n[Unit]\nDescription=MCPizer MCP Server\nAfter=network.target\n\n[Service]\nType=simple\nExecStart=/usr/local/bin/mcpizer\nEnvironment=\"MCPIZER_CONFIG_FILE=/etc/mcpizer/production.yaml\"\nRestart=always\nUser=mcpizer\n\n[Install]\nWantedBy=multi-user.target\n```\n\n\n\n## Troubleshooting\n\n### Debug Commands\n\n```bash\n# See what's happening\nMCPIZER_LOG_LEVEL=debug mcpizer -transport=stdio\n\n# Watch logs (STDIO mode)\ntail -f /tmp/mcpizer.log\n\n# Test your API is accessible\ncurl http://your-api-host:8000/openapi.json\n\n# Test gRPC reflection\ngrpcurl -plaintext your-grpc-host:50051 list\n```\n\n### Common Issues\n\n| Problem | Solution |\n|---------|----------|\n| \"No tools available\" | • Check API is running\u003cbr\u003e• Try direct schema URL\u003cbr\u003e• Check debug logs |\n| \"Connection refused\" | • Wrong port?\u003cbr\u003e• Check if API is running\u003cbr\u003e• Firewall blocking? |\n| \"String should have at most 64 characters\" | Update MCPizer - this is fixed in latest version |\n| gRPC \"connection refused\" | • Enable reflection in your gRPC server\u003cbr\u003e• Check with `grpcurl`\u003cbr\u003e• Or use .proto file approach instead |\n| \"Schema not found at base URL\" | • Specify exact schema path\u003cbr\u003e• Check if API exposes OpenAPI |\n| \".proto file missing server\" | • Add `server: grpc://host:port` to your config\u003cbr\u003e• Required for .proto files |\n\n## Examples\n\n### Complete Flow Example\n\nHere's how MCPizer works with a FastAPI service:\n\n```mermaid\nflowchart LR\n    subgraph \"Your FastAPI App\"\n        API[FastAPI Service\u003cbr/\u003ePort 8000]\n        Schema[\"/openapi.json\u003cbr/\u003eAuto-generated\"]\n        API --\u003e Schema\n    end\n    \n    subgraph \"MCPizer Config\"\n        Config[\"~/.mcpizer.yaml\u003cbr/\u003eschema_sources:\u003cbr/\u003ehttp://my-fastapi:8000\"]\n    end\n    \n    subgraph \"MCPizer Process\"\n        Discover[\"(1) Discover schema\u003cbr/\u003eat /openapi.json\"]\n        Convert[\"(2) Convert endpoints\u003cbr/\u003eto MCP tools\"]\n        Register[\"(3) Register tools\u003cbr/\u003ewith MCP protocol\"]\n        \n        Discover --\u003e Convert\n        Convert --\u003e Register\n    end\n    \n    subgraph \"AI Assistant\"\n        List[\"List tools:\u003cbr/\u003e• get_item\u003cbr/\u003e• create_item\u003cbr/\u003e• update_item\"]\n        Call[\"Call: get_item\u003cbr/\u003e{item_id: 123}\"]\n        Result[\"Result:\u003cbr/\u003e{id: 123, name: 'Test'}\"]\n        \n        List --\u003e Call\n        Call --\u003e Result\n    end\n    \n    Config --\u003e Discover\n    Schema --\u003e Discover\n    Register --\u003e List\n    Call --\u003e|HTTP GET /items/123| API\n    API --\u003e|JSON Response| Result\n    \n    style API fill:#e8f4fd\n    style Config fill:#fff4e6\n    style Register fill:#e8f5e9\n    style Result fill:#f3e5f5\n```\n\n### FastAPI Example\n\n```python\n# main.py\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\n@app.get(\"/items/{item_id}\")\ndef get_item(item_id: int, q: str = None):\n    return {\"item_id\": item_id, \"q\": q}\n\n# MCPizer auto-discovers at http://localhost:8000/openapi.json\n```\n\n### gRPC Example\n\n**Option 1: Using Reflection**\n```go\n// Enable reflection for MCPizer\nimport \"google.golang.org/grpc/reflection\"\n\nfunc main() {\n    s := grpc.NewServer()\n    pb.RegisterYourServiceServer(s, \u0026server{})\n    reflection.Register(s)  // This line enables MCPizer support\n    s.Serve(lis)\n}\n```\n\n**Option 2: Using .proto Files (Recommended for Production)**\n```yaml\n# config.yaml\nschema_sources:\n  # Your .proto file in version control\n  - url: github://myorg/protos/user-service.proto@v1.0.0\n    server: grpc://user-service.prod.example.com:443\n  \n  # Multiple environments, same schema\n  - url: github://myorg/protos/user-service.proto@v1.0.0\n    server: grpc://user-service.staging.example.com:443\n```\n\nBenefits:\n- ✅ No reflection needed in production\n- ✅ Version-controlled schemas\n- ✅ CI/CD can validate schemas\n- ✅ Same .proto for multiple environments\n\n## Development\n\n```bash\n# Run tests\ngo test ./...\n\n# Run integration tests (requires internet connection)\ngo test -tags=integration ./...\n\n# Build locally\ngo build -o mcpizer ./cmd/mcpizer\n\n# Run with example services (includes Petstore, gRPC test service, Jaeger)\ndocker compose up\n\n# Run individual examples\ncd examples/fastapi \u0026\u0026 pip install -r requirements.txt \u0026\u0026 python main.py\n```\n\nSee [examples/](examples/) for more complete examples:\n- [proto-config.yaml](examples/proto-config.yaml) - Using .proto files with multiple environments\n- [fastapi/](examples/fastapi/) - FastAPI integration example\n- [grpc-service/](examples/grpc-service/) - gRPC service with reflection\n\n## Contributing\n\nContributions welcome! Please:\n1. Check existing issues first\n2. Fork and create a feature branch\n3. Add tests for new functionality\n4. Submit a PR\n\n## License\n\nMIT - see [LICENSE](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi2y%2Fmcpizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fi2y%2Fmcpizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fi2y%2Fmcpizer/lists"}