GitHub MCP TypeScript SDK Server

# GitHub MCP TypeScript SDK Server A comprehensive Model Context Protocol (MCP) server for GitHub that provides access to repositories, issues, pull requests, commits, and user information through a standardized interface. Built with TypeScript and the official MCP SDK. ## 🚀 Features ### 📋 Available Tools (10 Total) - **`get_my_info`** - Get information about the authenticated GitHub user - **`get_repo_info`** - Get detailed information about a GitHub repository - **`list_repo_issues`** - List issues in a repository (with state filtering) - **`list_repo_prs`** - List pull requests in a repository - **`list_repo_commits`** - List recent commits in a repository - **`search_repositories`** - Search for repositories on GitHub - **`get_user_info`** - Get information about any GitHub user - **`list_user_repos`** - List repositories belonging to a user - **`get_my_repos`** - List repositories belonging to the authenticated user - **`get_github_stats`** - Get comprehensive GitHub statistics for a user ### 🔧 Capabilities - ✅ **Repository Information** - Name, description, stars, forks, language, visibility - ✅ **Issue Management** - List, filter, and view issue details - ✅ **Pull Request Tracking** - View PR status, authors, and details - ✅ **Commit History** - Browse recent commits with author and message info - ✅ **User Profiles** - Access user information and statistics - ✅ **Repository Search** - Advanced search with filters and sorting - ✅ **Statistics & Analytics** - Comprehensive user and repository metrics - ✅ **Error Handling** - Robust error handling with descriptive messages - ✅ **Natural Language Queries** - Ask questions in plain English ## 📦 Installation ### Prerequisites - Node.js 18+ - npm or yarn - GitHub Personal Access Token ### Setup 1. **Clone the repository:** ```bash git clone <your-repo-url> cd github-mcp-ts-sdk ``` 2. **Install dependencies:** ```bash npm install ``` 3. **Set up environment variables:** ```bash cp env.example .env # Edit .env and add your GitHub token ``` 4. **Build the project:** ```bash npm run build ``` ## 🔑 GitHub Token Setup 1. Go to [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens) 2. Click "Generate new token (classic)" 3. Select the following scopes: - `repo` (Full control of private repositories) - `user` (Read all user profile data) - `read:org` (Read org and team membership) 4. Copy the generated token and add it to your `.env` file: ```env GITHUB_TOKEN=your_github_token_here GITHUB_USERNAME=your_username_here # Optional ``` ## 🚀 Usage ### Development Mode ```bash npm run dev ``` ### Production Mode ```bash npm run build npm start ``` ### Watch Mode (for development) ```bash npm run build:watch ``` ### Test the Server ```bash npm test npm run simple-test npm run interactive-test npm run demo ``` ## 🛠 Tool Examples ### User Information #### Get Your GitHub Profile ```json { "tool": "get_my_info", "arguments": {} } ``` **Response:** ``` 👤 **My GitHub Profile** **Username:** Om-Shree-0709 **Name:** Om Shree **Bio:** Full Stack Developer **Followers:** 25 **Following:** 50 **Public Repositories:** 15 **Profile URL:** https://github.com/Om-Shree-0709 ``` #### Get User Information ```json { "tool": "get_user_info", "arguments": { "username": "microsoft" } } ``` ### Repository Information #### Get Repository Details ```json { "tool": "get_repo_info", "arguments": { "owner": "microsoft", "repo": "vscode" } } ``` **Response:** ``` 📁 **Repository: microsoft/vscode** **Description:** Visual Studio Code **Language:** TypeScript **Visibility:** public **Stars:** ⭐ 150000 **Forks:** 🍴 25000 **Watchers:** 👀 5000 **Created:** 1/1/2015 **Updated:** 12/15/2024 **URL:** https://github.com/microsoft/vscode ``` #### Search Repositories ```json { "tool": "search_repositories", "arguments": { "query": "language:typescript stars:>1000", "limit": 10 } } ``` **Advanced search examples:** - `language:javascript` - Search by programming language - `stars:>5000` - Filter by minimum stars - `user:octocat` - Search within a specific user's repositories - `language:python stars:>1000 forks:>100` - Combined filters - `created:>2023-01-01` - Filter by creation date - `topic:react` - Search by topic tags ### Issues and Pull Requests #### List Repository Issues ```json { "tool": "list_repo_issues", "arguments": { "owner": "facebook", "repo": "react", "state": "open" } } ``` #### List Pull Requests ```json { "tool": "list_repo_prs", "arguments": { "owner": "microsoft", "repo": "vscode", "state": "open" } } ``` ### Commit History #### List Recent Commits ```json { "tool": "list_repo_commits", "arguments": { "owner": "nodejs", "repo": "node", "limit": 20 } } ``` ### Statistics #### Get User Statistics ```json { "tool": "get_github_stats", "arguments": { "username": "torvalds" } } ``` **Response:** ``` 📊 **GitHub Statistics for torvalds** **User Info:** • Followers: 50000 • Following: 0 • Public Repos: 1 **Repository Stats:** • Total Repositories: 1 • Total Stars Received: ⭐ 200000 • Total Forks: 🍴 80000 • Average Stars per Repo: 200000.0 **Top Languages:** C: 1 ``` ## 📚 Resources ### Repository Resource Access repository data via URI: `github://repository/{owner}/{repo}` **Examples:** - `github://repository/microsoft/vscode` - `github://repository/facebook/react` ### User Resource Access user data via URI: `github://user/{username}` **Examples:** - `github://user/octocat` - `github://user/Om-Shree-0709` ## 💬 Prompts ### Natural Language Queries Ask questions in natural language about GitHub data: ```json { "prompt": "github_query", "arguments": { "query": "Show me my most starred repositories" } } ``` **Supported queries:** - "Show me my most starred repositories" - "Search for TypeScript repositories" - "What are the open issues in microsoft/vscode?" - "List my repositories" - "Get statistics for user octocat" ## 🔧 Configuration ### Environment Variables Create a `.env` file with: ```env # Required GITHUB_TOKEN=your_github_token_here # Optional GITHUB_USERNAME=your_username_here ``` ### GitHub Token Scopes Your GitHub token needs these scopes: - `repo` - Full control of private repositories - `user` - Read all user profile data - `read:org` - Read org and team membership ## 🏗 Architecture The server is built using: - **TypeScript** - Type-safe development - **MCP SDK** - Model Context Protocol framework - **Octokit** - Official GitHub API client - **Zod** - Schema validation - **Stdio Transport** - Standard input/output communication ### Project Structure ``` src/ ├── server.ts # Main server implementation with all tools and resources dist/ # Compiled JavaScript node_modules/ # Dependencies ``` ## 🔗 Integration ### With Claude Desktop Add to your Claude Desktop configuration: ```json { "mcpServers": { "github": { "command": "node", "args": ["/path/to/your/github-mcp-server/dist/server.js"], "env": { "GITHUB_TOKEN": "your_token_here" } } } } ``` ### With Other MCP Clients The server communicates via stdio and follows the MCP protocol specification. It works with any MCP-compatible client that can send JSON-RPC requests. ### Direct JSON-RPC Usage Send JSON-RPC 2.0 requests to your server: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_repo_info", "arguments": { "owner": "microsoft", "repo": "vscode" } } } ``` ## 🛡 Error Handling The server includes comprehensive error handling: - ✅ **Authentication errors** - Clear messages for invalid tokens - ✅ **Rate limiting** - Handles GitHub API rate limits gracefully - ✅ **Network errors** - Robust handling of connection issues - ✅ **Validation errors** - Input validation with helpful error messages - ✅ **GitHub API errors** - Detailed error reporting from GitHub ## 📈 Performance Features - **Efficient API usage** - Optimized requests with proper pagination - **Caching-friendly** - Responses designed for easy caching - **Rate limit aware** - Respects GitHub API rate limits - **Batch operations** - Efficient handling of multiple requests ## 🎯 Practical Use Cases ### 1. Repository Research ```json {"tool": "get_repo_info", "arguments": {"owner": "microsoft", "repo": "vscode"}} {"tool": "list_repo_issues", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}} {"tool": "list_repo_prs", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}} ``` ### 2. User Analysis ```json {"tool": "get_user_info", "arguments": {"username": "torvalds"}} {"tool": "get_github_stats", "arguments": {"username": "torvalds"}} {"tool": "list_user_repos", "arguments": {"username": "torvalds", "type": "all"}} ``` ### 3. Project Discovery ```json {"tool": "search_repositories", "arguments": {"query": "language:typescript stars:>1000"}} {"tool": "search_repositories", "arguments": {"query": "topic:machine-learning created:>2023-01-01"}} ``` ### 4. Your Own Data ```json {"tool": "get_my_info", "arguments": {}} {"tool": "get_my_repos", "arguments": {"type": "all"}} {"tool": "get_github_stats", "arguments": {"username": "Om-Shree-0709"}} ``` ## 📝 Development ### Available Scripts - `npm run build` - Build the TypeScript project - `npm run build:watch` - Build with file watching - `npm run dev` - Run in development mode - `npm start` - Run the compiled server - `npm test` - Test the server - `npm run setup` - Run setup script - `npm run demo` - Run demo script - `npm run interactive-test` - Run interactive tests ### Adding New Tools 1. Create a new function in `src/server.ts` 2. Register the tool with `server.registerTool()` 3. Add proper error handling 4. Update this README ### Testing ```bash # Build and test npm run build npm start # Test with various scripts npm test npm run simple-test npm run interactive-test npm run demo ``` ## 🚨 Troubleshooting ### Common Issues 1. **"Cannot find module" errors** - Run `npm install` to install dependencies - Run `npm run build` to compile TypeScript 2. **Authentication failures** - Check your GitHub token is valid - Ensure token has required scopes - Verify `.env` file exists and is readable 3. **Rate limit errors** - Wait before making more requests - Consider using a token with higher rate limits 4. **Repository not found** - Check owner and repository names are correct - Ensure repository is public or you have access ### Debug Mode Run in development mode for detailed logging: ```bash npm run dev ``` ## 📊 Response Format All tools return responses in the MCP standard format with `content` arrays containing text blocks: ```json { "content": [ { "type": "text", "text": "📁 **Repository: microsoft/vscode**\n\n**Description:** Visual Studio Code\n**Stars:** ⭐ 150000\n..." } ] } ``` ## 🤝 Contributing 1. Fork the repository 2. Create a feature branch 3. Add your changes 4. Test thoroughly 5. Submit a pull request ## 📄 License MIT License - see LICENSE file for details ## 🆘 Support - **Issues**: Report bugs and feature requests via GitHub Issues - **Documentation**: Check the MCP specification for protocol details - **GitHub API**: Refer to [GitHub's API documentation](https://docs.github.com/en/rest) ## 🔗 Related Links - [Model Context Protocol](https://modelcontextprotocol.io/) - [GitHub API Documentation](https://docs.github.com/en/rest) - [Octokit.js](https://octokit.github.io/rest.js/) - [TypeScript](https://www.typescriptlang.org/) --- **Happy coding! 🚀** Your GitHub MCP Server is ready with 10 powerful tools! You can: - ✅ Get any repository information - ✅ Search repositories with advanced filters - ✅ List issues and pull requests - ✅ Browse commit history - ✅ Get user profiles and statistics - ✅ Access your own GitHub data - ✅ Use natural language queries