{"id":25538613,"url":"https://github.com/getsimpletool/mcp-ws-example","last_synced_at":"2026-05-04T14:44:28.044Z","repository":{"id":268650801,"uuid":"905037925","full_name":"getsimpletool/mcp-ws-example","owner":"getsimpletool","description":"Anthropic's Model Context Protocol (MCP) Websocket Demo","archived":false,"fork":false,"pushed_at":"2024-12-18T04:17:22.000Z","size":158,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T05:17:41.273Z","etag":null,"topics":["ai","anthropic","anthropic-claude","fastapi","mcp","websocket"],"latest_commit_sha":null,"homepage":"https://modelcontextprotocol.io/","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/getsimpletool.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}},"created_at":"2024-12-18T03:19:04.000Z","updated_at":"2025-01-21T19:48:23.000Z","dependencies_parsed_at":"2024-12-18T05:35:26.284Z","dependency_job_id":null,"html_url":"https://github.com/getsimpletool/mcp-ws-example","commit_stats":null,"previous_names":["azdolinski/mpc-ws-example","azdolinski/mcp-ws-example","getsimpletool/mcp-ws-example"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fmcp-ws-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fmcp-ws-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fmcp-ws-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fmcp-ws-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsimpletool","download_url":"https://codeload.github.com/getsimpletool/mcp-ws-example/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239780142,"owners_count":19695736,"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":["ai","anthropic","anthropic-claude","fastapi","mcp","websocket"],"created_at":"2025-02-20T05:17:43.793Z","updated_at":"2026-01-31T04:30:16.228Z","avatar_url":"https://github.com/getsimpletool.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Message Communication Protocol (MCP) Implementations\n\nThis repository demonstrates two implementations of the Model Context Protocol (MCP) by [Anthropic AI](https://www.anthropic.com/news/model-context-protocol), a JSON-RPC based protocol for bi-directional communication that enables developers to build secure, two-way connections between their data sources and AI-powered tools.\n\n## 1. Memory Stream Implementation (run on same host)\n\n### Overview\nThe Memory Stream implementation demonstrates local client-server communication using in-memory channels. Both client and server operate within the same host.\n\n### Protocol Flow\n```\nClient                          Server\n   |                              |\n   |------ initialize() ---------\u003e|  (sends capabilities)\n   |\u003c---- InitializeResult -------|  (confirms connection)\n   |                              |\n   |------ list_tools() ---------\u003e|\n   |\u003c----- tool list -------------|\n   |                              |\n   |------ call_tool() ----------\u003e|\n   |\u003c----- tool result -----------|\n```\n\n### Key Components\n- **Memory Streams**: Uses `MemoryObjectSendStream` and `MemoryObjectReceiveStream` for message passing\n- **JSON-RPC Messages**: Implements standard JSON-RPC 2.0 message format\n- **Type Safety**: Utilizes Pydantic models for request/response validation\n\n## 2. WebSocket Implementation\n\n### Overview\nThe WebSocket implementation extends MCP over network connections using WebSocket protocol. In this demo, it provides weather information services using the National Weather Service API encapsulated via network in WebSocket messages.\n\n### Protocol Flow\n```\nClient                          Server\n   |                              |\n   |------ WebSocket Open -------\u003e|\n   |\u003c---- Connection Accept ------|\n   |                              |\n   |------ initialize() ---------\u003e|\n   |\u003c---- InitializeResult -------|\n   |                              |\n   |------ list_tools() ---------\u003e|\n   |\u003c----- weather tools ---------|\n```\n\n### Components\n\n1. **Server** (`websocket/server_ws.py`)\n```python\n@weather_server.list_tools()\nasync def handle_list_tools():\n    return [\n        Tool(\n            name=\"get-alerts\",\n            description=\"Get active weather alerts for a US state\",\n            inputSchema={\n                \"type\": \"object\",\n                \"required\": [\"state\"],\n                \"properties\": {\n                    \"state\": {\n                        \"type\": \"string\",\n                        \"description\": \"Two-letter state code (e.g. CA, NY)\"\n                    }\n                }\n            }\n        ),\n        Tool(\n            name=\"get-forecast\",\n            description=\"Get weather forecast for a location\",\n            inputSchema={\n                \"type\": \"object\",\n                \"required\": [\"latitude\", \"longitude\"],\n                \"properties\": {\n                    \"latitude\": {\n                        \"type\": \"number\",\n                        \"description\": \"Latitude of the location\"\n                    },\n                    \"longitude\": {\n                        \"type\": \"number\",\n                        \"description\": \"Longitude of the location\"\n                    }\n                }\n            }\n        )\n    ]\n```\n\n2. **Client** (`websocket/client_ws.py`)\n```python\nclient = WebSocketClient(\"ws://localhost:8000/ws\")\nawait client.connect()\ntools = await client.list_tools()\nforecast = await client.call_tool(\"get-forecast\", \n    {\"latitude\": 37.7749, \"longitude\": -122.4194})\n```\n\n### Available Weather Tools\n- **get-alerts**: Get active weather alerts for a US state (requires two-letter state code)\n- **get-forecast**: Get detailed weather forecast for a location (requires latitude and longitude)\n\n\n## Setup\n\n### Memory Stream Run (same host via MemoryStream)\n```bash\npip install -r requirements.txt\ncd memory_stream\npython test.py\n```\n\n### Websocket Run (client and server on different hosts)\n```bash\npip install -r requirements.txt\ncd websocket\npython test_ws.py\n```\n\nTest execution process:\n1. Server is started in a separate process\n2. System waits 2 seconds to ensure server initialization\n3. Client connects and executes test requests via FastAPI WebSocket port 8000\n4. Server process is gracefully terminated after tests\n\nTo run server client on two machins, you can use `run_server.py` and `run_client.py` script.\n\n\n\n\n## Additional Resources\n\nFor a detailed analysis of the client-server communication [port 8000], a PCAP (Packet Capture) file is available in the repository. This capture contains the complete WebSocket conversation between client and server components. This implementation is not encrypted, so the data is transmitted in plain text.\nThe PCAP file can be opened using Wireshark, a popular network protocol analyzer. It provides a comprehensive view of the communication, including the request headers and their content.\n\n[Download PCAP File](./websocket/pcap/test1.png)\n\n![IMG](./websocket/pcap/test1.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsimpletool%2Fmcp-ws-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsimpletool%2Fmcp-ws-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsimpletool%2Fmcp-ws-example/lists"}