How g-simmons/mcp-github-projects works
Project type and purpose
• This is a backend CLI application (“MCP server”) written in TypeScript/Node (using Bun) that exposes GitHub Projects v2, Issues, and Repositories operations over the Model Context Protocol (MCP) to AI agents or other clients.
• Its purpose is to accept MCP-style JSON requests (from tools like Smithery or Claude Desktop), execute the corresponding GitHub GraphQL API calls, and return structured responses.
File structure
• Top-level files:
• Dockerfile, bun.lock, package.json, tsconfig.json – project configuration and build
• smithery.yaml – MCP server metadata/commands definitions
• build.ts, codegen.ts – build and code-generation scripts
• src/:
• src/index.ts – MCP server entry point and request router
• src/common/ – shared error and utility functions
• src/graphql/ – .graphql query definitions organized by domain (issues, projects, repositories) and loader (graphql-loader.ts)
• src/operations/ – high-level operation handlers that invoke the GitHub client (issues.ts, projects.ts, repositories.ts, github-client.ts)
• src/types/ – generated TypeScript types for GraphQL schemas and GitHub API
• src/utils/ – helpers to load GraphQL documents
README for additional insights
• “Features” showing which GitHub API domains are covered
• Describes environment variables (GITHUB_TOKEN, GITHUB_OWNER) used for authenticating with GitHub’s GraphQL endpoint
• Provides CLI usage pattern: “bun build/index.js” plus env, which wires up to Smithery’s MCP client
a. Main components
• MCP Server Process (Node/Bun)
• MCP Request Router (index.ts)
• Operation Modules (issues, projects, repositories)
• GraphQL Loader (graphql-loader.ts + .graphql files)
• GitHub GraphQL Client (github-client.ts)
• External GitHub GraphQL API Endpoint
• MCP Client (e.g., Smithery or Claude Desktop)
• Build & Codegen Tools (build.ts, codegen.ts)
• Environment Configuration (.env / .env.example)
b. Relationships and interactions
• MCP Client → (stdin/stdout or socket) → MCP Server Process
• MCP Server uses Router → dispatches to Operation Module
• Operation Module → invokes GraphQL Client with query loaded by GraphQL Loader → sends HTTP request to GitHub API
• GitHub API responds → GraphQL Client returns data → Operation Module formats response → Router returns JSON to MCP Client
• Build/Codegen Tools read schema.docs.graphql + .graphql files → generate src/types GraphQL type definitions
c. Architectural patterns and design principles
• Modular separation: loader, client, operations, router
• Single responsibility: each module has one domain (issues/projects/repos)
• Code generation for type safety: GraphQL codegen script produces strongly typed operations
• Environmental configuration: credentials are injected via env vars
d. Key technologies and libraries
• Bun (runtime & build)
• TypeScript, tsconfig
• GraphQL (query files + codegen)
• Smithery MCP protocol (smithery.yaml)
• GitHub GraphQL API
• dotenv / .env files