{"id":26641152,"url":"https://github.com/quantgeekdev/mcp-framework","last_synced_at":"2025-05-15T23:05:08.147Z","repository":{"id":267197097,"uuid":"900493069","full_name":"QuantGeekDev/mcp-framework","owner":"QuantGeekDev","description":"A framework for writing MCP (Model Context Protocol) servers in Typescript","archived":false,"fork":false,"pushed_at":"2025-03-30T19:59:57.000Z","size":419,"stargazers_count":659,"open_issues_count":25,"forks_count":55,"subscribers_count":15,"default_branch":"main","last_synced_at":"2025-05-15T23:04:57.638Z","etag":null,"topics":["anthropic","claude","genai","llm","llms","mcp","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"https://mcp-framework.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QuantGeekDev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-12-08T22:37:28.000Z","updated_at":"2025-05-15T14:49:08.000Z","dependencies_parsed_at":"2025-02-23T00:30:44.307Z","dependency_job_id":"53225529-5d3e-4c74-b09c-ee727dd522f6","html_url":"https://github.com/QuantGeekDev/mcp-framework","commit_stats":null,"previous_names":["quantgeekdev/mcp-framework"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantGeekDev%2Fmcp-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantGeekDev%2Fmcp-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantGeekDev%2Fmcp-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuantGeekDev%2Fmcp-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QuantGeekDev","download_url":"https://codeload.github.com/QuantGeekDev/mcp-framework/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254436944,"owners_count":22070946,"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":["anthropic","claude","genai","llm","llms","mcp","modelcontextprotocol"],"created_at":"2025-03-24T18:19:55.020Z","updated_at":"2025-05-15T23:05:07.905Z","avatar_url":"https://github.com/QuantGeekDev.png","language":"TypeScript","readme":"# MCP Framework\n\nMCP-Framework is a framework for building Model Context Protocol (MCP) servers elegantly in TypeScript.\n\nMCP-Framework gives you architecture out of the box, with automatic directory-based discovery for tools, resources, and prompts. Use our powerful MCP abstractions to define tools, resources, or prompts in an elegant way. Our cli makes getting started with your own MCP server a breeze\n\n## Features\n\n- 🛠️ Automatic discovery and loading of tools, resources, and prompts\n- Multiple transport support (stdio, SSE, HTTP Stream)\n- TypeScript-first development with full type safety\n- Built on the official MCP SDK\n- Easy-to-use base classes for tools, prompts, and resources\n- Out of the box authentication for SSE endpoints\n\n\n# [Read the full docs here](https://mcp-framework.com)\n\n\n\n\n\n## Creating a repository with mcp-framework\n\n### Using the CLI (Recommended)\n\n```bash\n# Install the framework globally\nnpm install -g mcp-framework\n\n# Create a new MCP server project\nmcp create my-mcp-server\n\n# Navigate to your project\ncd my-mcp-server\n\n# Your server is ready to use!\n```\n\n## CLI Usage\n\nThe framework provides a powerful CLI for managing your MCP server projects:\n\n### Project Creation\n\n```bash\n# Create a new project\nmcp create \u003cyour project name here\u003e\n\n# Create a new project with the new EXPERIMENTAL HTTP transport\nHeads up: This will set cors allowed origin to \"*\", modify it in the index if you wish\nmcp create \u003cyour project name here\u003e --http --port 1337 --cors\n```\n\n# Options:\n# --http: Use HTTP transport instead of default stdio\n# --port \u003cnumber\u003e: Specify HTTP port (default: 8080)\n# --cors: Enable CORS with wildcard (*) access\n\n### Adding a Tool\n\n```bash\n# Add a new tool\nmcp add tool price-fetcher\n```\n\n### Adding a Prompt\n\n```bash\n# Add a new prompt\nmcp add prompt price-analysis\n```\n\n### Adding a Resource\n\n```bash\n# Add a new prompt\nmcp add resource market-data\n```\n\n## Development Workflow\n\n1. Create your project:\n\n```bash\n  mcp create my-mcp-server\n  cd my-mcp-server\n```\n\n2. Add tools as needed:\n\n   ```bash\n   mcp add tool data-fetcher\n   mcp add tool data-processor\n   mcp add tool report-generator\n   ```\n\n3. Build:\n\n   ```bash\n   npm run build\n\n   ```\n\n4. Add to MCP Client (Read below for Claude Desktop example)\n\n## Using with Claude Desktop\n\n### Local Development\n\nAdd this configuration to your Claude Desktop config file:\n\n**MacOS**: \\`~/Library/Application Support/Claude/claude_desktop_config.json\\`\n**Windows**: \\`%APPDATA%/Claude/claude_desktop_config.json\\`\n\n```json\n{\n\"mcpServers\": {\n\"${projectName}\": {\n      \"command\": \"node\",\n      \"args\":[\"/absolute/path/to/${projectName}/dist/index.js\"]\n}\n}\n}\n```\n\n### After Publishing\n\nAdd this configuration to your Claude Desktop config file:\n\n**MacOS**: \\`~/Library/Application Support/Claude/claude_desktop_config.json\\`\n**Windows**: \\`%APPDATA%/Claude/claude_desktop_config.json\\`\n\n```json\n{\n\"mcpServers\": {\n\"${projectName}\": {\n      \"command\": \"npx\",\n      \"args\": [\"${projectName}\"]\n}\n}\n}\n```\n\n## Building and Testing\n\n1. Make changes to your tools\n2. Run \\`npm run build\\` to compile\n3. The server will automatically load your tools on startup\n\n## Environment Variables\n\nThe framework supports the following environment variables for configuration:\n\n| Variable              | Description                                           | Default     |\n|-----------------------|-------------------------------------------------------|-------------|\n| MCP_ENABLE_FILE_LOGGING | Enable logging to files (true/false)                 | false       |\n| MCP_LOG_DIRECTORY     | Directory where log files will be stored             | logs        |\n| MCP_DEBUG_CONSOLE     | Display debug level messages in console (true/false) | false       |\n\nExample usage:\n\n```bash\n# Enable file logging\nMCP_ENABLE_FILE_LOGGING=true node dist/index.js\n\n# Specify a custom log directory\nMCP_ENABLE_FILE_LOGGING=true MCP_LOG_DIRECTORY=my-logs\n# Enable debug messages in console\nMCP_DEBUG_CONSOLE=true```\n\n## Quick Start\n\n### Creating a Tool\n\n```typescript\nimport { MCPTool } from \"mcp-framework\";\nimport { z } from \"zod\";\n\ninterface ExampleInput {\n  message: string;\n}\n\nclass ExampleTool extends MCPTool\u003cExampleInput\u003e {\n  name = \"example_tool\";\n  description = \"An example tool that processes messages\";\n\n  schema = {\n    message: {\n      type: z.string(),\n      description: \"Message to process\",\n    },\n  };\n\n  async execute(input: ExampleInput) {\n    return `Processed: ${input.message}`;\n  }\n}\n\nexport default ExampleTool;\n```\n\n### Setting up the Server\n\n```typescript\nimport { MCPServer } from \"mcp-framework\";\n\nconst server = new MCPServer();\n\n// OR (mutually exclusive!) with SSE transport\nconst server = new MCPServer({\n  transport: {\n    type: \"sse\",\n    options: {\n      port: 8080            // Optional (default: 8080)\n    }\n  }\n});\n\n// Start the server\nawait server.start();\n```\n\n## Transport Configuration\n\n### stdio Transport (Default)\n\nThe stdio transport is used by default if no transport configuration is provided:\n\n```typescript\nconst server = new MCPServer();\n// or explicitly:\nconst server = new MCPServer({\n  transport: { type: \"stdio\" }\n});\n```\n\n### SSE Transport\n\nTo use Server-Sent Events (SSE) transport:\n\n```typescript\nconst server = new MCPServer({\n  transport: {\n    type: \"sse\",\n    options: {\n      port: 8080,            // Optional (default: 8080)\n      endpoint: \"/sse\",      // Optional (default: \"/sse\")\n      messageEndpoint: \"/messages\", // Optional (default: \"/messages\")\n      cors: {\n        allowOrigin: \"*\",    // Optional (default: \"*\")\n        allowMethods: \"GET, POST, OPTIONS\", // Optional (default: \"GET, POST, OPTIONS\")\n        allowHeaders: \"Content-Type, Authorization, x-api-key\", // Optional (default: \"Content-Type, Authorization, x-api-key\")\n        exposeHeaders: \"Content-Type, Authorization, x-api-key\", // Optional (default: \"Content-Type, Authorization, x-api-key\")\n        maxAge: \"86400\"      // Optional (default: \"86400\")\n      }\n    }\n  }\n});\n```\n\n### HTTP Stream Transport\n\nTo use HTTP Stream transport:\n\n```typescript\nconst server = new MCPServer({\n  transport: {\n    type: \"http-stream\",\n    options: {\n      port: 8080,                // Optional (default: 8080)\n      endpoint: \"/mcp\",          // Optional (default: \"/mcp\") \n      responseMode: \"batch\",     // Optional (default: \"batch\"), can be \"batch\" or \"stream\"\n      batchTimeout: 30000,       // Optional (default: 30000ms) - timeout for batch responses\n      maxMessageSize: \"4mb\",     // Optional (default: \"4mb\") - maximum message size\n      \n      // Session configuration\n      session: {\n        enabled: true,           // Optional (default: true)\n        headerName: \"Mcp-Session-Id\", // Optional (default: \"Mcp-Session-Id\")\n        allowClientTermination: true, // Optional (default: true)\n      },\n      \n      // Stream resumability (for missed messages)\n      resumability: {\n        enabled: false,          // Optional (default: false)\n        historyDuration: 300000, // Optional (default: 300000ms = 5min) - how long to keep message history\n      },\n      \n      // CORS configuration\n      cors: {\n        allowOrigin: \"*\"         // Other CORS options use defaults\n      }\n    }\n  }\n});\n```\n\n#### Response Modes\n\nThe HTTP Stream transport supports two response modes:\n\n1. **Batch Mode** (Default): Responses are collected and sent as a single JSON-RPC response. This is suitable for typical request-response patterns and is more efficient for most use cases.\n\n2. **Stream Mode**: All responses are sent over a persistent SSE connection opened for each request. This is ideal for long-running operations or when the server needs to send multiple messages in response to a single request.\n\nYou can configure the response mode based on your specific needs:\n\n```typescript\n// For batch mode (default):\nconst server = new MCPServer({\n  transport: {\n    type: \"http-stream\",\n    options: {\n      responseMode: \"batch\"\n    }\n  }\n});\n\n// For stream mode:\nconst server = new MCPServer({\n  transport: {\n    type: \"http-stream\",\n    options: {\n      responseMode: \"stream\"\n    }\n  }\n});\n```\n\n#### HTTP Stream Transport Features\n\n- **Session Management**: Automatic session tracking and management\n- **Stream Resumability**: Optional support for resuming streams after connection loss\n- **Batch Processing**: Support for JSON-RPC batch requests/responses\n- **Comprehensive Error Handling**: Detailed error responses with JSON-RPC error codes\n\n## Authentication\n\nMCP Framework provides optional authentication for SSE endpoints. You can choose between JWT and API Key authentication, or implement your own custom authentication provider.\n\n### JWT Authentication\n\n```typescript\nimport { MCPServer, JWTAuthProvider } from \"mcp-framework\";\nimport { Algorithm } from \"jsonwebtoken\";\n\nconst server = new MCPServer({\n  transport: {\n    type: \"sse\",\n    options: {\n      auth: {\n        provider: new JWTAuthProvider({\n          secret: process.env.JWT_SECRET,\n          algorithms: [\"HS256\" as Algorithm], // Optional (default: [\"HS256\"])\n          headerName: \"Authorization\"         // Optional (default: \"Authorization\")\n        }),\n        endpoints: {\n          sse: true,      // Protect SSE endpoint (default: false)\n          messages: true  // Protect message endpoint (default: true)\n        }\n      }\n    }\n  }\n});\n```\n\nClients must include a valid JWT token in the Authorization header:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n```\n\n### API Key Authentication\n\n```typescript\nimport { MCPServer, APIKeyAuthProvider } from \"mcp-framework\";\n\nconst server = new MCPServer({\n  transport: {\n    type: \"sse\",\n    options: {\n      auth: {\n        provider: new APIKeyAuthProvider({\n          keys: [process.env.API_KEY],\n          headerName: \"X-API-Key\" // Optional (default: \"X-API-Key\")\n        })\n      }\n    }\n  }\n});\n```\n\nClients must include a valid API key in the X-API-Key header:\n```\nX-API-Key: your-api-key\n```\n\n### Custom Authentication\n\nYou can implement your own authentication provider by implementing the `AuthProvider` interface:\n\n```typescript\nimport { AuthProvider, AuthResult } from \"mcp-framework\";\nimport { IncomingMessage } from \"node:http\";\n\nclass CustomAuthProvider implements AuthProvider {\n  async authenticate(req: IncomingMessage): Promise\u003cboolean | AuthResult\u003e {\n    // Implement your custom authentication logic\n    return true;\n  }\n\n  getAuthError() {\n    return {\n      status: 401,\n      message: \"Authentication failed\"\n    };\n  }\n}\n```\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantgeekdev%2Fmcp-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantgeekdev%2Fmcp-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantgeekdev%2Fmcp-framework/lists"}