examples

MCP GitHub Project Manager Examples

This directory contains example code demonstrating how to use the MCP GitHub Project Manager for various project management tasks.

Table of Contents

• Directory Structure
• Running the Examples
  • Prerequisites
  • Setup
• Installation Options
  • Using npm
  • Install globally
  • Run with TypeScript
  • Install in AI Assistants
    • Claude
    • Roocode
    • Windsurf
    • VS Code
    • Cursor
    • Using Docker
    • Troubleshooting
• Basic Examples
• Advanced Examples
• Integration Examples
• Best Practices
• Contributing
• License

Directory Structure

• basic/ - Basic examples for common operations
• advanced/ - Advanced examples for complex scenarios
• integration/ - Examples showing integration with other systems and frameworks

Running the Examples

Prerequisites

1. Node.js 18.x or higher
2. TypeScript installed (npm install -g typescript ts-node)
3. MCP GitHub Project Manager installed (npm install mcp-github-project-manager)
4. Valid GitHub token with appropriate permissions

Setup

# Install the package
npm install mcp-github-project-manager

# Configure environment variables
export GITHUB_TOKEN=your_github_token
export GITHUB_OWNER=your_github_username_or_org
export GITHUB_REPO=your_repository_name

# Run an example
ts-node examples/basic/create-simple-project.ts

Installation Options

Option 1: Using npm (for application integration)

# Install in your project
npm install mcp-github-project-manager

Option 2: Install globally (for CLI usage)

# Install globally
npm install -g mcp-github-project-manager

# Run the MCP server with environment variables
mcp-github-project-manager

# Or run with command line arguments
mcp-github-project-manager --token=your_token --owner=your_username --repo=your_repo

# Display help information
mcp-github-project-manager --help

Option 3: Run directly with TypeScript

# Run directly with ts-node
node --loader ts-node/esm src/index.ts

# Run with command line arguments
node --loader ts-node/esm src/index.ts --token=your_token --owner=your_username --repo=your_repo

# Use the npm dev script (watches for changes)
npm run dev

# Display help information
node --loader ts-node/esm src/index.ts --help

Option 4: Install in AI Assistants

Claude

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Roocode

Add this to your Roocode configuration:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Windsurf

Add this to your Windsurf MCP configuration:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

VS Code

Add this to your VS Code MCP configuration:

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

Cursor

Add this to your Cursor MCP configuration:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

See the main README for more detailed installation instructions for various AI assistants.

Using Docker

You can also run the MCP server in a Docker container:

{
  "mcpServers": {
    "github-project-manager": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "github-project-manager-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

See the main README for instructions on building the Docker image.

Troubleshooting

If you encounter issues with the MCP server:

1. Try using bunx instead of npx if you have module resolution issues
2. On Windows, use cmd /c npx -y mcp-github-project-manager as the command
3. Check that your GitHub token has the required permissions
4. Ensure you're using Node.js v18 or higher

See the main README for more troubleshooting tips.

Basic Examples

Create Simple Project

basic/create-simple-project.ts

Creates a basic project with a single milestone and two issues.

ts-node examples/basic/create-simple-project.ts

Plan Sprint

basic/plan-sprint.ts

Plans a sprint with existing issues.

ts-node examples/basic/plan-sprint.ts

Track Progress

basic/track-progress.ts

Tracks the progress of a sprint.

ts-node examples/basic/track-progress.ts

Advanced Examples

Coming soon:

• Creating complex roadmaps with multiple milestones
• Working with custom fields
• Performing batch operations
• Implementing automation workflows

Integration Examples

Coming soon:

• Integration with GitHub Actions
• Integration with Slack for notifications
• Generating reports and visualizations
• Implementing custom workflows

Best Practices

1. Error Handling: All examples include proper error handling to demonstrate how to handle various error scenarios.

2. Configuration: Use environment variables or command line arguments for configuration. Command line arguments take precedence over environment variables.

3. Validation: Always validate input data before making API calls.

4. Rate Limiting: Be mindful of GitHub API rate limits, especially when running multiple examples in succession.

Contributing

Feel free to contribute additional examples by following the Contributing Guide.

License

These examples are licensed under the same license as the main project.

Integration Examples

Node.js Integration

import { Server } from "mcp-github-project-manager";

const server = new Server({
  transport: "stdio",
  config: {
    githubToken: process.env.GITHUB_TOKEN
  }
});

server.start();

Using with OpenAI Function Calling

import { OpenAI } from "openai";
import { spawn } from "child_process";
import { McpClient } from "@modelcontextprotocol/client";

// Start MCP server as a child process
// Option 1: Using environment variables
const serverProcess = spawn("mcp-github-project-manager", [], {
  env: { ...process.env, GITHUB_TOKEN: "your_token" }
});

// Option 2: Using command line arguments
// const serverProcess = spawn("mcp-github-project-manager", [
//   "--token", "your_token",
//   "--owner", "your_username",
//   "--repo", "your_repo"
// ]);

// Create MCP client
const mcpClient = new McpClient({
  transport: {
    type: "process",
    process: serverProcess
  }
});

// Get available tools
const tools = await mcpClient.listTools();

// Configure OpenAI with tools
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const completion = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Create a project roadmap for Q3 2025" }],
  tools: tools.map(tool => ({
    type: "function",
    function: {
      name: tool.name,
      description: tool.description,
      parameters: tool.parameters
    }
  }))
});

// Handle tool calls from OpenAI
if (completion.choices[0].message.tool_calls) {
  // Process and execute tool calls with MCP client
}

See individual example files for more details and use cases.