{"id":31924617,"url":"https://github.com/agent-hellboy/py-mcp","last_synced_at":"2025-10-14T00:06:06.158Z","repository":{"id":302310184,"uuid":"1011749565","full_name":"Agent-Hellboy/py-mcp","owner":"Agent-Hellboy","description":"A Simple Framework for Creating an MCP Server using sse protocol","archived":false,"fork":false,"pushed_at":"2025-08-25T20:34:43.000Z","size":620,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-25T22:25:13.261Z","etag":null,"topics":["mcp","mcp-framework","mcp-python-sdk","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Agent-Hellboy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-07-01T09:32:27.000Z","updated_at":"2025-08-25T20:35:02.000Z","dependencies_parsed_at":"2025-08-25T22:13:24.781Z","dependency_job_id":"e6c00f1d-112e-4ff0-9795-c87a7710e421","html_url":"https://github.com/Agent-Hellboy/py-mcp","commit_stats":null,"previous_names":["agent-hellboy/basic-python-mcp","agent-hellboy/py-sse-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Agent-Hellboy/py-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Hellboy%2Fpy-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Hellboy%2Fpy-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Hellboy%2Fpy-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Hellboy%2Fpy-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Agent-Hellboy","download_url":"https://codeload.github.com/Agent-Hellboy/py-mcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Agent-Hellboy%2Fpy-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279017382,"owners_count":26086052,"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","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"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":["mcp","mcp-framework","mcp-python-sdk","mcp-server"],"created_at":"2025-10-14T00:06:01.419Z","updated_at":"2025-10-14T00:06:06.149Z","avatar_url":"https://github.com/Agent-Hellboy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-mcp\n\n[![Build Status](https://github.com/Agent-Hellboy/py-sse-mcp/actions/workflows/python-ci.yml/badge.svg)](https://github.com/Agent-Hellboy/py-sse-mcp/actions/workflows/python-ci.yml)\n[![codecov](https://codecov.io/gh/Agent-Hellboy/py-sse-mcp/branch/master/graph/badge.svg)](https://codecov.io/gh/Agent-Hellboy/py-sse-mcp)\n\nA Simple Framework for Creating an MCP Server using sse protocol\n\n\nThis project was created after encountering several issues(I faced it while trying cursor as a client) with **sse transport protocol** of [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk). The basic setup was inspired by [b3nelof0n/node-mcp-server](https://github.com/b3nelof0n/node-mcp-server/blob/main/server.js).\n\n## Usage\n\nRun the example server:\n   ```bash\n   pip install .\n   python example/run_server.py\n   ```\n\n**Note:** Targeting Cursor as a client only.\n\n## Writing Your Own Tool\n\nTo create a tool with this framework, use the `@tool_registry.register` decorator. For example:\n\n```python\nfrom pymcp.registry import tool_registry\n\n@tool_registry.register\ndef my_tool(a: int, b: int) -\u003e str:\n    \"\"\"Adds two numbers and returns the result as a string.\"\"\"\n    return f\"Result: {a + b}\"\n```\n\n## Hosting the Server with FastAPI and Uvicorn\n\nThe framework provides a FastAPI app factory (`pymcp.applications.create_app`). You can use this to create and configure your server, including middleware and compression:\n\n```python\nfrom pymcp.applications import create_app\nimport uvicorn\n\n# Example: Enable GZip compression and add custom middleware\nfrom fastapi import Request, Response\n\nclass CustomHeaderMiddleware:\n    def __init__(self, app):\n        self.app = app\n    async def __call__(self, scope, receive, send):\n        async def send_wrapper(message):\n            if message[\"type\"] == \"http.response.start\":\n                headers = dict(message.get(\"headers\", []))\n                headers[b\"x-custom-middleware\"] = b\"true\"\n                message[\"headers\"] = list(headers.items())\n            await send(message)\n        await self.app(scope, receive, send_wrapper)\n\nfrom pymcp.middleware import MiddlewareConfig\n\nmiddleware_config = MiddlewareConfig(\n    compression={\"enabled\": True},\n    custom=[CustomHeaderMiddleware]\n)\n\napp = create_app(middleware_config=middleware_config)\n\nif __name__ == \"__main__\":\n    uvicorn.run(app, host=\"0.0.0.0\", port=8088)\n```\n\n## Configuring Middleware\n\nTo add custom or extra middleware (such as GZip, CORS, or your own), use the `MiddlewareConfig` and pass it to `create_app`:\n\n```python\nfrom pymcp.applications import create_app\nfrom pymcp.middleware import MiddlewareConfig\n\n# Example: Add your own custom middleware class\nclass MyCustomMiddleware:\n    def __init__(self, app):\n        self.app = app\n    async def __call__(self, scope, receive, send):\n        # ... your logic ...\n        await self.app(scope, receive, send)\n\nmiddleware_config = MiddlewareConfig(\n    compression={\"enabled\": True},  # Enables GZip\n    custom=[MyCustomMiddleware]\n)\n\napp = create_app(middleware_config=middleware_config)\n```\n\n**Note:**  \n- The framework automatically applies CORS and other standard middleware.\n- You can stack as many custom middleware as you like using the `custom` list in `MiddlewareConfig`.\n- For simple per-route logic, you can still use FastAPI's `@app.middleware(\"http\")` decorator after creating the app, but the preferred way is via `MiddlewareConfig` for global middleware.\n\nRequest flow of an example mcp server \n![mcp](./mcp.png)\n\n## Logging\n\nBy default, the framework does not configure logging. To see debug or info logs from the framework, configure logging in your application (before importing or running the server):\n\n```python\nimport logging\nlogging.basicConfig(level=logging.DEBUG)  # or INFO, WARNING, etc.\n```\n\nThis allows you to control the verbosity and destination of log messages from both your code and the framework.\n\n## Middleware Configuration\n\nCheck [guide.md](./guide.md).\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-hellboy%2Fpy-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-hellboy%2Fpy-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-hellboy%2Fpy-mcp/lists"}