@enhance-pm/mcp-server

MCP (Model Context Protocol) server for Enhance. Connects IDE agents like Claude Code, Cursor, and Windsurf to your Enhance workspace for code intelligence, issue management, and knowledge search.

Architecture

IDE Agent (Claude Code / Cursor / Windsurf)
  │  stdio transport (local subprocess)
  ▼
@enhance-pm/mcp-server (this package)
  │  HTTP + Bearer auth
  ▼
repo-worker /mcp/* routes (Fastify)
  │  Auth middleware → workspace context
  ▼
Enhance services (Prisma, search, RAG, etc.)

The MCP server runs as a local subprocess spawned by your IDE. It communicates with your Enhance instance over HTTP using an API key for authentication.

Quick Start

1. Create an API Key

Go to Workspace Settings > MCP (or Project Settings > MCP Keys) and create an API key. Copy the key — it's shown only once.

2. Configure Your IDE

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "enhance": {
      "command": "node",
      "args": ["./packages/mcp-server/dist/index.js"],
      "env": {
        "ENHANCE_API_URL": "https://your-instance.example.com",
        "ENHANCE_API_KEY": "byg_live_..."
      }
    }
  }
}

Cursor

Add to Cursor's MCP settings (Settings > MCP Servers):

{
  "enhance": {
    "command": "npx",
    "args": ["@enhance-pm/mcp-server"],
    "env": {
      "ENHANCE_API_URL": "https://your-instance.example.com",
      "ENHANCE_API_KEY": "byg_live_..."
    }
  }
}

3. Restart Your IDE

After adding the configuration, restart your IDE agent. The Enhance tools will appear in the tool list.

Configuration

The server loads configuration from environment variables or a .enhance.json file.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | ENHANCE_API_KEY | Yes | API key (format: byg_live_<40 hex chars>) | | ENHANCE_API_URL | Yes | URL of your Enhance instance |

Legacy environment variables BYGGDRASIL_API_KEY and BYGGDRASIL_API_URL are also supported as fallbacks.

Config File Fallback

If environment variables are not set, the server looks for config files in this order:

1. .enhance.json in current working directory
2. .byggdrasil.json in current working directory (legacy fallback)
3. ~/.enhance.json in home directory
4. ~/.byggdrasil.json in home directory (legacy fallback)

{
  "apiKey": "byg_live_...",
  "apiUrl": "https://your-instance.example.com"
}

Tools (13)

Search

| Tool | Description | Required Scope | |------|-------------|----------------| | search_code | Multi-strategy code search (semantic, path, graph) | search:read | | search_knowledge | RAG search across documentation and knowledge base | search:read | | search_issues | Semantic issue search using natural language | search:read |

Issues

| Tool | Description | Required Scope | |------|-------------|----------------| | list_issues | List issues with filters (status, priority, type) | issues:read | | get_issue | Get full issue details including affected files | issues:read | | create_issue | Create a new issue in a project | issues:write | | update_issue | Update issue title, description, status, priority, type, or tags | issues:write |

Code Context

| Tool | Description | Required Scope | |------|-------------|----------------| | get_codebase_map | Get repository architecture (domains, entry points, module graph, tech stack) | code:read | | get_file_content | Read a specific file from a repository | code:read |

Wiki

| Tool | Description | Required Scope | |------|-------------|----------------| | list_wiki_pages | List wiki pages in a project | wiki:read | | get_wiki_page | Get full wiki page content | wiki:read | | create_wiki_page | Create a new wiki page | wiki:write | | update_wiki_page | Update a wiki page's title or content | wiki:write |

Resources (4)

Resources provide browsable data that MCP clients can list and read:

| Resource | URI Pattern | Description | |----------|-------------|-------------| | Projects | enhance://projects | All projects in the workspace | | Repositories | enhance://project/{projectId}/repositories | Repositories linked to a project | | Issues | enhance://project/{projectId}/issues | Recent issues in a project | | Documents | enhance://project/{projectId}/documents | Wiki/documentation pages in a project |

Prompts (2)

Prompts provide pre-built multi-step workflows:

investigate

Multi-step codebase investigation workflow. Searches code, knowledge base, and issues to understand how something works.

Parameters:

• query (required) — The question to investigate
• projectId (required) — Enhance project ID
• repositoryId (optional) — Repository ID (if omitted, the prompt asks the agent to discover it)

Steps performed:

1. Search the knowledge base
2. Search the codebase
3. Read key files
4. Check the codebase map
5. Search related issues
6. Synthesize findings

create-issue-from-context

Create a well-structured issue from code context. Searches the codebase first to understand scope and affected files.

Parameters:

• title (required) — Issue title
• description (required) — Context for the issue
• projectId (required) — Enhance project ID
• repositoryId (optional) — Repository ID

Steps performed:

1. Search for existing similar issues
2. Search the codebase for affected files
3. Analyze scope using codebase map
4. Create the issue with full context
5. Report created issue and related issues

Authentication & Scopes

API keys use the format byg_live_<40 hex chars>. Keys are hashed (SHA-256) before storage — the raw key is shown only once at creation time.

Available Scopes

| Scope | Description | |-------|-------------| | search:read | Search code, knowledge base, and issues | | issues:read | List and read issues | | issues:write | Create and update issues | | code:read | Read codebase maps and file contents | | wiki:read | List and read wiki pages | | wiki:write | Create and update wiki pages |

Keys can be workspace-scoped (access all projects) or project-scoped (access only one project).

Default Scopes

New keys created from the UI get: search:read, issues:read, code:read, wiki:read

Project-scoped keys created from project settings get all scopes: search:read, issues:read, issues:write, code:read, wiki:read, wiki:write

Local Testing

Step 1: Start the repo-worker in dev mode

Dev mode bypasses API key authentication so you don't need a real key. Open a terminal:

cd apps/repo-worker
MCP_DEV_MODE=true MCP_DEV_WORKSPACE_ID=<your-workspace-id> MCP_DEV_USER_ID=<your-user-id> pnpm dev

Replace <your-workspace-id> and <your-user-id> with actual IDs from your local database (check Prisma Studio with cd packages/prisma && pnpm db:studio). If you omit them, they default to "dev" which works for basic route testing but won't return real data.

The repo-worker starts at http://localhost:3001.

Step 2: Build the MCP server

cd packages/mcp-server
pnpm build

Step 3: Test with the MCP Inspector

The MCP Inspector is an interactive web UI for testing MCP servers. It lets you browse tools, resources, and prompts, and call them manually.

cd packages/mcp-server
ENHANCE_API_URL=http://localhost:3001 ENHANCE_API_KEY=dev \
  npx @modelcontextprotocol/inspector node dist/index.js

This opens a browser UI where you can:

• See all 13 tools, 4 resources, and 2 prompts listed
• Call search_code with a repository ID and query
• Call list_issues to see issues in a project
• Browse enhance://projects to list workspace projects
• Test the investigate prompt workflow

Step 4: Test with Claude Code

Add a .mcp.json file in your project root:

{
  "mcpServers": {
    "enhance": {
      "command": "node",
      "args": ["/absolute/path/to/byggdrasil/packages/mcp-server/dist/index.js"],
      "env": {
        "ENHANCE_API_URL": "http://localhost:3001",
        "ENHANCE_API_KEY": "dev"
      }
    }
  }
}

Restart Claude Code. You should see the Enhance tools in the tool list. Try asking:

• "List my Enhance projects" (uses the projects resource)
• "Search for authentication code in repo X" (uses search_code)
• "Show me recent issues" (uses list_issues)

Step 5: Test with a real API key (optional)

To test the full auth flow instead of dev mode:

1. Start the repo-worker without MCP_DEV_MODE:

   cd apps/repo-worker && pnpm dev

2. Start the web app:

   cd apps/web && pnpm dev

3. Go to Workspace Settings > MCP and create an API key. Copy it.

4. Use the real key:

   cd packages/mcp-server
   ENHANCE_API_URL=http://localhost:3001 ENHANCE_API_KEY=byg_live_... \
     npx @modelcontextprotocol/inspector node dist/index.js

5. Verify:

   • Valid key → tools work
   • Revoke the key in the UI → requests return 401
   • Key with only search:read scope → create_issue returns 403

Troubleshooting

| Problem | Fix | |---------|-----| | Missing API key error on startup | Set ENHANCE_API_KEY env var | | Enhance API error: 401 | Key is invalid/revoked, or repo-worker isn't in dev mode | | Enhance API error: 403 | Key lacks the required scope for that tool | | ECONNREFUSED localhost:3001 | Repo-worker isn't running — start it with pnpm dev | | Tools return empty results | Make sure your workspace has indexed repositories and issues | | Cannot find module './dist/index.js' | Run pnpm build in packages/mcp-server first |

Project Structure

packages/mcp-server/
├── src/
│   ├── index.ts          # Entry point (stdio transport, graceful shutdown)
│   ├── server.ts         # MCP server factory
│   ├── client.ts         # HTTP client for /mcp/* API routes
│   ├── config.ts         # Configuration loading (env + .enhance.json)
│   ├── formatters.ts     # Human-readable output formatters
│   ├── tools/
│   │   └── index.ts      # 13 MCP tool registrations
│   ├── resources/
│   │   └── index.ts      # 4 MCP resource registrations
│   └── prompts/
│       └── index.ts      # 2 MCP prompt registrations
├── package.json
└── tsconfig.json

API Routes Reference

The MCP server communicates with these repo-worker routes:

Search

• POST /mcp/search/code — Multi-strategy code search
• POST /mcp/search/knowledge — RAG knowledge base search
• POST /mcp/search/issues — Semantic issue search

Issues

• GET /mcp/issues/:issueId — Get issue details
• POST /mcp/issues/list — List issues with filters
• POST /mcp/issues — Create issue (scope: issues:write)
• PATCH /mcp/issues/:issueId — Update issue (scope: issues:write)

Code Context

• GET /mcp/codebase-map/:repositoryId — Get codebase map
• POST /mcp/file — Read file content

Resources

• GET /mcp/projects — List workspace projects
• GET /mcp/projects/:projectId/repositories — List project repositories
• GET /mcp/projects/:projectId/issues — List project issues
• GET /mcp/projects/:projectId/documents — List project documents

Wiki

• GET /mcp/wiki?projectId=... — List wiki pages
• GET /mcp/wiki/:pageId — Get wiki page
• POST /mcp/wiki — Create wiki page (scope: wiki:write)
• PUT /mcp/wiki/:pageId — Update wiki page (scope: wiki:write)