{"id":51255665,"url":"https://github.com/supershaneski/bun-mcp-server","last_synced_at":"2026-06-29T10:02:10.281Z","repository":{"id":367214460,"uuid":"1279741723","full_name":"supershaneski/bun-mcp-server","owner":"supershaneski","description":"A lightweight HTTP-based Model Context Protocol (MCP) server built with Bun.","archived":false,"fork":false,"pushed_at":"2026-06-25T02:47:53.000Z","size":13,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T04:15:05.706Z","etag":null,"topics":["bun","http","http-transport","javascript","mcp","mcp-server","tool-registry"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/supershaneski.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-25T01:27:32.000Z","updated_at":"2026-06-25T02:47:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/supershaneski/bun-mcp-server","commit_stats":null,"previous_names":["supershaneski/bun-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/supershaneski/bun-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supershaneski%2Fbun-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supershaneski%2Fbun-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supershaneski%2Fbun-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supershaneski%2Fbun-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supershaneski","download_url":"https://codeload.github.com/supershaneski/bun-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supershaneski%2Fbun-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34921807,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"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":["bun","http","http-transport","javascript","mcp","mcp-server","tool-registry"],"created_at":"2026-06-29T10:02:04.431Z","updated_at":"2026-06-29T10:02:10.272Z","avatar_url":"https://github.com/supershaneski.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bun-mcp-server\n\nA lightweight HTTP-based [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server built with [Bun](https://bun.sh).\n\n## Motivation\n\nThis project explores the MCP lifecycle through a clean, modular implementation built with **Bun**. By separating HTTP routing from JSON-RPC 2.0 handling, the architecture aims to remain transport-agnostic, providing a clear reference for how the protocol functions under the hood.\n\n\u003e [!Note]\n\u003e This is an educational, work-in-progress implementation and does not cover the full MCP specification.\n\n---\n\n本プロジェクトは、**Bun** を使用したクリーンかつモジュール化された実装を通じて、MCP（Model Context Protocol）のライフサイクルを探求するものです。HTTPルーティングとJSON-RPC 2.0の処理を分離することでトランスポート層に依存しない設計を実現し、プロトコルの内部動作を理解するためのリファレンスとして機能します。\n\n\u003e [!Note]\n\u003e 本プロジェクトは学習・研究用であり、MCP仕様のすべてを実装しているわけではありません。\n\n\nYou can read the full MCP specification [here](https://modelcontextprotocol.io/specification/2025-11-25/basic).\n\n\n## Features\n\n- **HTTP Transport** — Serves MCP over a standard HTTP `POST` endpoint (`/mcp`), compatible with any MCP client that supports the HTTP transport.\n- **JSON-RPC 2.0** — Fully compliant request/response framing with proper error codes (`-32700`, `-32600`, `-32601`, `-32602`, `-32603`).\n- **Tool Registry** — Pluggable tool system for easy registration and execution of tools.\n\n## Project Structure\n\n```\nbun-mcp-server/\n├── src/\n│   ├── index.js          # Entry point — starts the Bun HTTP server on port 3000\n│   ├── lib/\n│   │   └── utils.js      # Shared utilities (timestamps, CORS headers, logging, IP parsing)\n│   ├── mcp/\n│   │   ├── index.js      # Core MCP request handler (JSON-RPC dispatch)\n│   │   └── tools.js      # Tool definitions and registration\n│   └── routes/\n│       └── index.js      # HTTP route definitions (/mcp, /.well-known/mcp, catch-all)\n├── package.json\n├── jsconfig.json\n└── BRIEF.md              # Project brief / requirements\n```\n\n## Prerequisites\n\n- [Bun](https://bun.sh) v1.3+ installed\n\n## Getting Started\n\n### Install dependencies\n\n```bash\nbun install\n```\n\n### Start the server\n\n```bash\nbun run dev\n```\n\nThe server starts on **http://localhost:3000** with file-watching enabled for live reload during development.\n\n## API Endpoints\n\n### `POST /mcp`\n\nThe main MCP endpoint. Accepts JSON-RPC 2.0 requests and dispatches them to the appropriate handler.\n\n**Supported methods:**\n\n| Method | Description |\n| --- | --- |\n| `initialize` | Handshake — returns server info, protocol version, and capabilities |\n| `tools/list` | Returns the list of available tools with their schemas |\n| `tools/call` | Executes a registered tool by name with the given arguments |\n| `notifications/initialized` | Acknowledges client initialization (returns `202`) |\n| `notifications/roots/list_changed` | Acknowledges root change notifications (returns `202`) |\n\n### `GET /.well-known/mcp`\n\nThis endpoint serves as the **MCP Server Card**. It provides essential metadata about the server—such as its name, description, supported transport types, and the base URL for the MCP endpoint—allowing clients to identify and connect to the service automatically.\n\nWhile this mechanism is not currently part of the official Model Context Protocol (MCP) specification, it addresses a critical gap: enabling HTTP-based MCP servers to be discoverable via standard web patterns and simplifying the process for users to add them to their environments.\n\nThe return value will be mapped to the client's MCP server config file:\n```json\n{\n  \"servers\": {\n    \"weather-server\": {\n      \"type\": \"http\",\n      \"url\": \"http://localhost/mcp\"\n    }\n  }\n}\n```\n\n### `* /*`\n\nCatch-all route that returns a `404 Not Found` JSON response for any unmatched path.\n\n## Usage Examples\n\n### Initialize the server\n\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 1,\n    \"method\": \"initialize\",\n    \"params\": {\n      \"protocolVersion\": \"2024-11-05\",\n      \"capabilities\": {},\n      \"clientInfo\": { \"name\": \"test-client\", \"version\": \"1.0.0\" }\n    }\n  }'\n```\n\n### List available tools\n\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 2,\n    \"method\": \"tools/list\"\n  }'\n```\n\n### Call a tool\n\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"jsonrpc\": \"2.0\",\n    \"id\": 3,\n    \"method\": \"tools/call\",\n    \"params\": {\n      \"name\": \"get_weather\",\n      \"arguments\": { \"city\": \"Tokyo\" }\n    }\n  }'\n```\n\n### Discover the server\n\n```bash\ncurl http://localhost:3000/.well-known/mcp\n```\n\n## Live Testing\n\nYou can verify that the server is functioning correctly by connecting it to an MCP client, such as VS Code or AntiGravity.\n\n## VSCode\nFollow these steps to configure and connect:\n\n1. Create or open `.vscode/mcp.json` in your project directory.\n2. Add the following entry:\n```json\n{\n  \"servers\": {\n    \"weather-server\": {\n      \"url\": \"http://localhost:3000/mcp\",\n      \"headers\": {\n        \"Content-Type\": \"application/json\"\n      }\n    }\n  }\n}\n\n```\n3. In the VS Code Chat panel, click the **gear icon** to open the **Agent Customizations** dialog.\n4. Select **MCP Servers** from the sidebar. You should see `weather-server` listed under **Workspace**.\n5. Right-click `weather-server` and select **Start Server** from the context menu to initialize the connection.\n\n### AntiGravity\nFollow these steps to configure and connect:\n\n1. **Open Configuration:** Navigate to **Additional Options** (`...`) and select **MCP Servers**.\n2. **Manage Servers:** Click **Manage MCP Servers**, then select **View raw config** to open the `mcp_config.json` file.\n3. **Add Server:** Add the following configuration:\n```json\n{\n  \"mcpServers\": {\n    \"weather-server\": {\n      \"serverUrl\": \"http://localhost:3000/mcp\",\n      \"headers\": {\n        \"Content-Type\": \"application/json\"\n      }\n    }\n  }\n}\n\n```\n4. **Connect:** Save the file, return to the **Manage MCP Servers** menu, and click **Refresh**.\n\n---\n\u003e [!Note] \n\u003e Ensure your MCP server is already running locally before connecting to either one. Upon success, you will see connection activity in your server’s console logs.\n\n\nOnce connected, confirm that tool discovery and execution are working by sending a prompt through your IDE's chat interface:\n\n\u003e *\"Let's test the MCP server. Get the weather for Tokyo today.\"*\n\nIf successful, the chat should trigger the tool and return the relevant data from your server.\n\n\n## Available Tools\n\n| Tool | Description | Parameters |\n| --- | --- | --- |\n| `get_weather` | Get the current weather for a given city | `city` (string, required) |\n\n\u003e The `get_weather` tool returns simulated data (random temperature, \"Cloudy\" condition) — it is included as a demo tool for testing the MCP lifecycle.\n\n## Adding New Tools\n\nRegister new tools in [`src/mcp/tools.js`](src/mcp/tools.js) using the tool registry:\n\n```js\ntoolRegistry.register(\n  \"my_tool\",\n  {\n    name: \"my_tool\",\n    title: \"My Tool\",\n    description: \"Does something useful.\",\n    parameters: {\n      type: \"object\",\n      properties: {\n        input: { type: \"string\", description: \"Some input value\" }\n      },\n      required: [\"input\"]\n    }\n  },\n  async ({ input }) =\u003e {\n    // Your tool logic here\n    return { result: `Processed: ${input}` }\n  }\n)\n```\n\nThe tool is automatically available via `tools/list` and executable via `tools/call` — no additional wiring needed.\n\n## Error Handling\n\nThe server returns standard JSON-RPC 2.0 error responses:\n\n| Code | Meaning |\n| --- | --- |\n| `-32700` | Parse error — malformed JSON body |\n| `-32600` | Invalid Request — missing `jsonrpc` or `method` |\n| `-32601` | Method not found — unsupported MCP method |\n| `-32602` | Invalid params — missing or malformed tool parameters |\n| `-32603` | Internal error — unexpected server-side failure |\n\n## License\n\nMIT © supershaneski\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupershaneski%2Fbun-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupershaneski%2Fbun-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupershaneski%2Fbun-mcp-server/lists"}