@gdd/mcp-server

MCP server for GDD framework - enables AI agents to use GDD via Model Context Protocol.

What is GDD MCP Server?

The GDD MCP Server exposes GDD functionality as MCP tools, allowing AI agents (Claude, Cursor, etc.) to:

• Load only relevant documentation nodes (70-90% token reduction)
• Check system health
• Validate documentation
• Predict which nodes are drifting

Installation

npm install -g @gdd/mcp-server

Or use with npx (recommended):

npx @gdd/mcp-server

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gdd": {
      "command": "npx",
      "args": ["@gdd/mcp-server"],
      "env": {
        "GDD_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Cursor

Add to Cursor settings (MCP configuration):

{
  "mcpServers": {
    "gdd": {
      "command": "npx",
      "args": ["@gdd/mcp-server"],
      "env": {
        "GDD_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Available Tools

resolve_context

Resolves node dependencies and loads optimal context.

Input:

{
  "node_names": ["feature-a", "feature-b"],
  "max_tokens": 4000
}

Output:

{
  "nodes": [
    {
      "id": "feature-a",
      "content": "...",
      "file_path": "/path/to/docs/nodes-v2/feature-a.md",
      "token_count": 1234,
      "depth": 0,
      "reason": "requested"
    }
  ],
  "total_tokens": 1234
}

health_score

Gets health score of the GDD system.

Input: {}

Output:

{
  "score": 98.46,
  "breakdown": {
    "system_map_alignment": 100,
    "dependency_density": 100,
    "crosslink_score": 92.31,
    "ssot_alignment": 100,
    "narrative_consistency": 100
  },
  "status": "healthy",
  "nodes_detected": 15,
  "nodes_total": 15,
  "nodes_missing": 0
}

validate_system

Validates the GDD system for errors and warnings.

Input: {}

Output:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "info": [],
  "summary": {
    "total_issues": 0,
    "error_count": 0,
    "warning_count": 0,
    "info_count": 0
  }
}

predict_drift

Predicts which nodes are drifting (becoming outdated).

Input: {}

Output:

{
  "overall_risk": 23,
  "high_risk_nodes": [],
  "medium_risk_nodes": [
    {
      "node": "legacy-integration",
      "risk": 45,
      "reasons": [
        "Not updated in 60 days",
        "Coverage 65% (target 90%)",
        "3 broken crosslinks"
      ],
      "recommendation": "Add tests, update documentation"
    }
  ],
  "low_risk_nodes": []
}

Environment Variables

• GDD_WORKSPACE: Path to project root (default: current working directory)

Troubleshooting

Server fails to start

Error: "GDD_WORKSPACE environment variable not set"

• Set GDD_WORKSPACE to your project root directory
• Or ensure you're running from a directory with system-map-v2.yaml

Error: "Failed to initialize GDD"

• Verify system-map-v2.yaml exists in workspace
• Check that docs/nodes-v2/ directory exists
• Ensure system-map is valid YAML

Tools return errors

Error: "Node not found"

• Verify node name exists in system-map
• Check node name spelling

Error: "Documentation file not found"

• Ensure node files exist in docs/nodes-v2/
• Check paths in system-map docs field

Examples

See examples/mcp-usage for:

• Claude Desktop configuration
• Cursor configuration
• Usage scenarios
• Expected outputs

License

MIT