{"id":29180474,"url":"https://github.com/flarexio/mcpblade","last_synced_at":"2026-04-24T22:31:24.388Z","repository":{"id":301357998,"uuid":"1005105878","full_name":"flarexio/mcpblade","owner":"flarexio","description":"MCPBlade is a powerful aggregation and management service for Model Control Protocol (MCP) servers. It provides intelligent tool discovery, semantic search, and smart routing capabilities to seamlessly work with multiple MCP servers.","archived":false,"fork":false,"pushed_at":"2025-06-26T12:11:20.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-26T13:24:03.354Z","etag":null,"topics":["mcp","mcp-edge","mcp-hub","mcp-nats","mcp-proxy","nats"],"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/flarexio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2025-06-19T17:16:06.000Z","updated_at":"2025-06-26T12:12:51.000Z","dependencies_parsed_at":"2025-06-26T13:34:48.277Z","dependency_job_id":null,"html_url":"https://github.com/flarexio/mcpblade","commit_stats":null,"previous_names":["flarexio/mcpblade"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flarexio/mcpblade","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flarexio%2Fmcpblade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flarexio%2Fmcpblade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flarexio%2Fmcpblade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flarexio%2Fmcpblade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flarexio","download_url":"https://codeload.github.com/flarexio/mcpblade/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flarexio%2Fmcpblade/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263025171,"owners_count":23401736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["mcp","mcp-edge","mcp-hub","mcp-nats","mcp-proxy","nats"],"created_at":"2025-07-01T19:31:31.778Z","updated_at":"2026-04-24T22:31:19.369Z","avatar_url":"https://github.com/flarexio.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCPBlade\n\nMCPBlade is a powerful aggregation and management service for Model Control Protocol (MCP) servers. It provides intelligent tool discovery, semantic search, and smart routing capabilities to seamlessly work with multiple MCP servers.\n\n## Features\n\n- **Tool Aggregation**: Combines tools from multiple MCP servers into a unified interface\n- **Semantic Search**: Vector-based search to find tools using natural language queries\n- **Smart Routing**: Automatically routes tool calls to the correct backend server\n- **Health Monitoring**: Continuous health checks and heartbeat monitoring for all connected servers\n- **Persistent \u0026 Temporary Servers**: Support for both persistent configuration-based and temporary runtime servers\n- **Multiple Transport Types**: Support for stdio, SSE, and streamable HTTP transports for backend connections\n- **NATS Integration**: Distributed service communication via NATS messaging with microservices support\n- **HTTP API**: RESTful API and MCP-compatible streaming endpoints\n- **Middleware Architecture**: Logging, proxy, and other middleware support\n\n## Architecture\n\nMCPBlade consists of several key components:\n\n- **Core Service** ([`service.go`](service.go)): Main business logic and MCP server management\n- **Vector Search** ([`vector/`](vector/)): Tool indexing and semantic search capabilities  \n- **Transport Layer**: \n  - [`transport/nats/`](transport/nats/): NATS-based communication\n  - [`transport/http/`](transport/http/): HTTP API endpoints\n- **Persistence** ([`persistence/chromem/`](persistence/chromem/)): Vector database implementation\n- **MCP Integration** ([`mcp/`](mcp/)): MCP protocol endpoint handlers\n- **Proxy Layer** ([`proxy.go`](proxy.go)): Service proxy middleware for distributed deployments\n\n## Installation\n\n```bash\ngo install github.com/flarexio/mcpblade/cmd/mcpblade@latest\ngo install github.com/flarexio/mcpblade/cmd/mcpblade_mcp_server@latest\n```\n\n## Configuration\n\nCreate a configuration file `config.yaml` (see [`config.example.yaml`](config.example.yaml) for reference):\n\n```yaml\nmcpServers:\n  time:\n    transport: stdio\n    command: uvx\n    args: [ \"mcp-server-time\", \"--local-timezone=Asia/Taipei\" ]\ncacheRefreshTTL: 5m\nvector:\n  enabled: true\n  persistent: true\n  collection: tools\n```\n\n### Supported Transport Types\n\n- **stdio**: Standard input/output communication with subprocess\n- **sse**: Server-Sent Events over HTTP\n- **streamable-http**: HTTP streaming protocol\n\n## Usage\n\n### Running the Core Service\n\n```bash\n# Run with default configuration path (~/.flarex/mcpblade)\nmcpblade\n\n# Run with custom configuration path\nmcpblade --path /path/to/config\n\n# Enable HTTP API\nmcpblade --http --http-addr :8080\n\n# Connect to custom NATS server\nmcpblade --nats nats://localhost:4222\n```\n\n### Running as MCP Server\n\n```bash\n# Connect to shared MCPBlade instance\nmcpblade_mcp_server --edge-id your-edge-id\n\n# Run dedicated server with specific MCP backend\nmcpblade_mcp_server --edge-id your-edge-id --server-id my-server --cmd \"uvx mcp-server-time\"\n\n# Connect to custom NATS server\nmcpblade_mcp_server --edge-id your-edge-id --nats nats://localhost:4222\n```\n\n## API Reference\n\n### Core Service Interface\n\nThe [`Service`](service.go) interface provides these methods:\n\n- **RegisterMCPServer**: Add a new MCP server to the registry\n- **UnregisterMCPServer**: Remove an MCP server from the registry  \n- **ListTools**: Get all available tools from registered servers\n- **SearchTools**: Search for tools using semantic queries\n- **Forward**: Route MCP requests to appropriate backend servers\n- **Close**: Gracefully shutdown the service\n\n### HTTP API Endpoints\n\nWhen HTTP transport is enabled:\n\n```bash\n# RESTful API\nPOST   /api/mcp/register           # Register MCP server\nDELETE /api/mcp/unregister/:id     # Unregister MCP server\nGET    /api/mcp/tools              # List all tools\nGET    /api/mcp/tools/search       # Search tools\nPOST   /api/mcp/forward            # Forward tool calls\n\n# MCP Protocol\nPOST   /mcp/                       # MCP JSON-RPC endpoint\n```\n\n### Example Tool Search\n\n```go\n// Semantic search for tools\ntools, err := service.SearchTools(ctx, \"what's the current time?\", 5)\nif err != nil {\n    return err\n}\n\nfor _, tool := range tools {\n    fmt.Printf(\"Tool: %s - %s\\n\", tool.Name, tool.Description)\n}\n```\n\n### Example Tool Call\n\n```go\nreq := mcp.CallToolRequest{\n    Request: mcp.Request{Method: \"tools/call\"},\n    Params: mcp.CallToolParams{\n        Name: \"get_current_time\",\n        Arguments: map[string]any{\n            \"timezone\": \"Asia/Taipei\",\n        },\n    },\n}\n\nresult, err := service.Forward(ctx, req)\nif err != nil {\n    return err\n}\n\n// Handle result\nif !result.IsError {\n    for _, content := range result.Content {\n        fmt.Printf(\"Result: %v\\n\", content)\n    }\n}\n```\n\n## Transport Architecture\n\n```\n[MCP Clients] \n    ↓ (stdio/nats/http)\n[MCPBlade Proxy/Service]\n    ↓ (stdio/sse/streamable-http)  \n[Backend MCP Servers]\n```\n\n### Flow Description\n\n1. **Inbound**: Clients connect to MCPBlade via:\n   - **stdio**: Native MCP protocol (via [`mcpblade_mcp_server`](cmd/mcpblade_mcp_server/main.go))\n   - **nats**: Distributed messaging (via [`transport/nats/`](transport/nats/))\n   - **http**: RESTful API and MCP streaming (via [`transport/http/`](transport/http/))\n\n2. **Processing**: MCPBlade aggregates, searches, and routes requests using:\n   - Tool caching and deduplication\n   - Vector-based semantic search  \n   - Health monitoring and heartbeat tracking\n\n3. **Outbound**: MCPBlade connects to backend servers as an MCP client via:\n   - **stdio**: Subprocess communication\n   - **sse**: Server-Sent Events\n   - **streamable-http**: HTTP streaming\n\n## Vector Search\n\nTools are automatically indexed in a vector database for intelligent search:\n\n```go\n// Search finds tools using semantic similarity\ntools, err := service.SearchTools(ctx, \"time and date functions\", 10)\n\n// Tools are indexed with metadata including:\n// - Server ID\n// - Tool name and description\n// - Input schema\n// - Full tool JSON for reconstruction\n```\n\nThe vector implementation uses [ChromeDB](https://github.com/philippgille/chromem-go) with support for:\n- In-memory collections for development\n- Persistent storage for production\n- Automatic embedding generation\n- Similarity search with configurable result limits\n\n## Health Monitoring\n\nThe service continuously monitors the health of all registered MCP servers:\n\n- **Periodic Health Checks**: Configurable TTL-based monitoring\n- **Heartbeat Tracking**: Atomic timestamp tracking for each server\n- **Automatic Recovery**: Failed servers can be automatically restarted\n- **Cache Refresh**: Tool cache is refreshed based on health status\n- **Graceful Degradation**: Failed servers are excluded from routing\n\n## Middleware System\n\nMCPBlade uses a middleware architecture for cross-cutting concerns:\n\n### Logging Middleware\n\n```go\nsvc = mcpblade.LoggingMiddleware(logger)(svc)\n```\n\nProvides structured logging with [Zap](https://github.com/uber-go/zap) for all service operations.\n\n### Proxy Middleware  \n\n```go\nsvc = mcpblade.ProxyMiddleware(endpoints)(svc)\n```\n\nEnables distributed deployments by proxying calls through NATS endpoints.\n\n## Development\n\n### Running Tests\n\n```bash\n# Run all tests\ngo test ./...\n\n# Run with race detection\ngo test -race ./...\n\n# Run specific test suite\ngo test ./service_test.go\n```\n\n### Project Structure\n\n```\n├── cmd/\n│   ├── mcpblade/                    # Main service executable\n│   └── mcpblade_mcp_server/         # MCP server implementation\n├── transport/\n│   ├── nats/                        # NATS transport layer\n│   │   ├── transport.go             # NATS handlers\n│   │   ├── factory.go               # NATS client endpoints\n│   │   └── topic.go                 # NATS topic routing\n│   └── http/                        # HTTP transport layer\n│       ├── transport.go             # HTTP handlers\n│       ├── mcp.go                   # MCP streaming endpoints\n│       └── router.go                # Route configuration\n├── persistence/chromem/             # ChromeDB vector database\n├── vector/                          # Vector database interfaces\n├── mcp/                            # MCP protocol handlers\n│   ├── endpoint.go                  # MCP endpoint implementations\n│   └── endpoint_test.go             # MCP protocol tests\n├── service.go                       # Core service implementation\n├── service_test.go                  # Service integration tests\n├── model.go                         # Data models and types\n├── model_test.go                    # Model serialization tests\n├── endpoint.go                      # Go-kit endpoints\n├── proxy.go                         # Proxy middleware\n├── logging.go                       # Logging middleware\n└── config.example.yaml              # Example configuration\n```\n\n## Dependencies\n\n- [mcp-go](https://github.com/mark3labs/mcp-go): MCP protocol implementation\n- [chromem-go](https://github.com/philippgille/chromem-go): Vector database\n- [nats.go](https://github.com/nats-io/nats.go): NATS messaging with microservices\n- [go-kit](https://github.com/go-kit/kit): Microservice toolkit for endpoints\n- [gin](https://github.com/gin-gonic/gin): HTTP web framework\n- [zap](https://github.com/uber-go/zap): Structured logging\n- [cli/v3](https://github.com/urfave/cli): Command-line interface\n\n## License\n\nMIT License - see [LICENSE.md](LICENSE.md) for details.\n\nThis project is part of the FlareX ecosystem.\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. All tests pass: `go test ./...`\n2. Code follows Go conventions\n3. New features include tests\n4. Documentation is updated\n5. Commit messages are descriptive\n\nFor major changes, please open an issue first to discuss the proposed changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflarexio%2Fmcpblade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflarexio%2Fmcpblade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflarexio%2Fmcpblade/lists"}