A Model Context Protocol (MCP) server for coding agents to externalize state via GitHub Issues, Projects, and Wiki.

"A tool for coding agents to externalize state."

GitHub becomes the persistent brain; the agent is the stateless hands. The agent reconstructs context from queries, acts, and persists results—all through gh CLI.

# Clone repository
git clone https://github.com/Mnehmos/mnehmos.personal.github.mcp.git
cd mnehmos.personal.github.mcp

# Install dependencies
npm install

# Build
npm run build

# Ensure gh CLI is authenticated
gh auth status

Add to your MCP client configuration:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["path/to/mnehmos.personal.github.mcp/dist/index.js"]
    }
  }
}

Manage GitHub issues with composite operations.

Actions: create, get, update, close, reopen, comment, search, list, batch_update

// Create a research task
{
  "action": "create",
  "repo": "owner/repo",
  "title": "Research: OAuth2 options",
  "body": "Compare passport.js vs oauth2-client",
  "labels": ["research", "todo"]
}

// Batch update multiple issues
{
  "action": "batch_update",
  "repo": "owner/repo",
  "operations": [
    { "issue": 42, "labels": { "add": ["in-progress"], "remove": ["todo"] } },
    { "issue": 43, "state": "closed", "comment": "Done!" }
  ]
}

Reconstruct session context for agent startup.

Actions: get, set_focus, get_blockers, get_timeline

// Full context at session start
{
  "action": "get",
  "repo": "owner/repo",
  "include": ["active_tasks", "blockers", "in_progress", "prs"]
}

Output:

🎮 Session Context
Repository: owner/repo
══════════════════════════════════════════════════════

🚨 BLOCKERS:
   🔴 #45 Database migration fails (blocks: #42, #43)

🔄 In Progress:
   🟠 #42 Implement OAuth2 auth
      Assignee: @mnehmos | Started: 2h ago

📋 Active Tasks:
   🟡 #46 Add error handling
   ⬜ #47 Write tests

Manage GitHub Projects (Kanban boards).

Actions: list, get, get_column, move, add_item, remove_item

{
  "action": "get",
  "repo": "owner/repo",
  "project": "Development Board"
}

Output:

📋 Project: Development Board
══════════════════════════════════════════════════════

📥 Todo (3)              🔄 In Progress (2)      ✅ Done (8)
─────────────────────    ─────────────────────   ─────────────
#45 Add error types      #42 OAuth2 auth         #38 Lexer
#46 Parser fixes         #43 Token refresh       #39 AST nodes

Persist documentation and architectural decisions.

Actions: list, get, create, update, search

{
  "action": "create",
  "repo": "owner/repo",
  "page": "ADR-001-Auth",
  "content": "# ADR-001: Authentication\n\n## Decision\nUse OAuth2...",
  "message": "Add ADR-001"
}

Track issue relationships and dependencies.

Actions: add, remove, get_graph, find_blockers, find_cycles

{
  "action": "get_graph",
  "repo": "owner/repo",
  "issue": 42,
  "depth": 2
}

Output:

🗺️ Dependency Graph for #42
────────────────────────────────────────

Nodes:
  🟢 #42 Implement OAuth2 auth
  🔴 #45 Database migration (blocker)
  🟢 #43 Token refresh

Relationships:
  #42 → blocked_by → #45
  #43 → blocked_by → #42

⚠️ Cycles detected:
  🔄 #42 → #43 → #42

Labels are automatically normalized:

// Reconstruct context in ONE call
const ctx = await github_context({
  action: "get",
  repo: "Mnehmos/my-project",
  include: ["active_tasks", "blockers", "in_progress"],
});
// Agent now knows:
// - What tasks are assigned
// - What's blocking progress
// - What's currently in flight

// 1. Create task
await github_issue({
  action: "create",
  repo,
  title: "Research OAuth2",
  labels: ["research"],
});

// 2. Start working
await github_issue({
  action: "batch_update",
  repo,
  operations: [
    { issue: 42, labels: { add: ["in-progress"], remove: ["todo"] } },
  ],
});

// 3. Document findings
await github_issue({
  action: "comment",
  repo,
  issue: 42,
  comment: "## Findings\n...",
});

// 4. Complete
await github_issue({
  action: "close",
  repo,
  issue: 42,
  comment: "Done. Decision: passport.js",
});

// 5. Create follow-up
await github_issue({
  action: "create",
  repo,
  title: "Implement OAuth2 with passport.js",
});

# Run in dev mode
npm run dev

# Type check
npm run typecheck

# Run tests
npm test

# Build
npm run build

• Node.js 18+
• GitHub CLI (gh) 2.4.0+ authenticated (for --json flag support)
• Repository access for target operations

Note for Mac users: If you get unknown flag: --json, update your gh CLI: brew upgrade gh

MIT

• mnehmos.synch.mcp - Local agent memory bank
• mnehmos.ooda.mcp - Full computer control
• Stateful MCP Architecture - Design patterns