{"id":28436956,"url":"https://github.com/epicweb-dev/epic-mcp","last_synced_at":"2025-10-04T06:59:00.530Z","repository":{"id":286005208,"uuid":"958259731","full_name":"epicweb-dev/epic-mcp","owner":"epicweb-dev","description":"An example of the Epic Stack with a /mcp endpoint","archived":false,"fork":false,"pushed_at":"2025-04-09T14:21:07.000Z","size":8854,"stargazers_count":31,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-05T23:08:07.868Z","etag":null,"topics":["epic-stack","epic-stack-example"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/epicweb-dev.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":"2025-03-31T22:55:03.000Z","updated_at":"2025-05-26T07:29:12.000Z","dependencies_parsed_at":"2025-04-03T20:41:16.871Z","dependency_job_id":null,"html_url":"https://github.com/epicweb-dev/epic-mcp","commit_stats":null,"previous_names":["epicweb-dev/epic-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/epicweb-dev/epic-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Fepic-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Fepic-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Fepic-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Fepic-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epicweb-dev","download_url":"https://codeload.github.com/epicweb-dev/epic-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epicweb-dev%2Fepic-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262327296,"owners_count":23294246,"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":["epic-stack","epic-stack-example"],"created_at":"2025-06-05T23:08:06.472Z","updated_at":"2025-10-04T06:58:55.508Z","avatar_url":"https://github.com/epicweb-dev.png","language":"TypeScript","readme":"# Epic MCP\n\nAn [Epic Stack](https://github.com/epicweb-dev/epic-stack) example adding\nsupport for the Model Context Protocol (MCP).\n\n## What is MCP?\n\nThe Model Context Protocol (MCP) is an open protocol that standardizes how\napplications provide context to Large Language Models (LLMs). Think of MCP like\na USB-C port for AI applications - it provides a standardized way to connect AI\nmodels to different data sources and tools.\n\nLearn more from the\n[MCP Documentation](https://modelcontextprotocol.io/introduction)\n\n## Example Implementation\n\nThis repository demonstrates how to integrate MCP into an Epic Stack\napplication. The implementation includes:\n\n1. Server-side MCP setup for handling client connections\n2. SSE (Server-Sent Events) transport layer for real-time communication\n3. Example tool implementations showing how to expose functionality to LLMs\n\n### Key Components\n\n#### 1. MCP Server Setup (`app/routes/mcp+/mcp.server.ts`)\n\n```ts\nexport const server = new McpServer(\n\t{\n\t\tname: 'epic-mcp-a25d',\n\t\tversion: '1.0.0',\n\t},\n\t{\n\t\tcapabilities: {\n\t\t\ttools: {},\n\t\t},\n\t},\n)\n```\n\nThe MCP server is the core component that handles tool registration and\nexecution. It's configured with a unique name and version, and defines the\ncapabilities it provides.\n\n#### 2. Tool Implementation\n\n```ts\nserver.tool(\n\t'Find User',\n\t'Search for users in the Epic Notes database by their name or username',\n\t{ query: z.string().describe('The query to search for') },\n\tasync ({ query }) =\u003e {\n\t\t// Implementation...\n\t},\n)\n```\n\nTools are the primary way to expose functionality to LLMs. Each tool:\n\n- Has a descriptive name and purpose\n- Uses Zod for type-safe parameter validation\n- Can return multiple content types (text, images, etc.)\n- Integrates with your existing application logic\n\n#### 3. Transport Layer (`app/routes/mcp+/fetch-transport.server.ts`)\n\nThe transport layer handles the bi-directional communication between the MCP\nclient and server:\n\n- Uses Server-Sent Events (SSE) for real-time server-to-client communication\n- Handles POST requests for client-to-server messages\n- Maintains session state for multiple concurrent connections\n\n#### 4. Route Integration (`app/routes/mcp+/index.ts`)\n\n```ts\nexport async function loader({ request }: Route.LoaderArgs) {\n\tconst url = new URL(request.url)\n\tconst sessionId = url.searchParams.get('sessionId')\n\tconst transport = await connect(sessionId)\n\treturn transport.handleSSERequest(request)\n}\n```\n\nThe Remix route:\n\n- Establishes SSE connections for real-time communication\n- Handles incoming tool requests via POST endpoints\n- Manages session state for multiple clients\n\n### Learning Points\n\n1. **Tool Design**: When designing tools for LLMs:\n\n   - Provide clear, descriptive names and purposes\n   - Use strong type validation for parameters\n   - Return structured responses that LLMs can understand\n   - Consider supporting multiple content types (text, images, etc.)\n\n2. **State Management**: The implementation demonstrates:\n\n   - Session-based connection tracking\n   - Clean connection cleanup on client disconnect\n   - Safe concurrent client handling\n\n3. **Integration Patterns**: Learn how to:\n\n   - Connect MCP with existing application logic\n   - Handle real-time communication in Remix\n   - Structure your MCP implementation for maintainability\n\n4. **Security Considerations**:\n   - Session-based access control\n   - Safe handling of client connections\n   - Proper cleanup of resources\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicweb-dev%2Fepic-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepicweb-dev%2Fepic-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepicweb-dev%2Fepic-mcp/lists"}