npm package: @graphito/mcp-server
Description: Model Context Protocol server for Graphito - enables AI agents to access documentation graphs
Latest version: 0.9.0

# @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

```bash
npm install -g @gdd/mcp-server
```

Or use with npx (recommended):

```bash
npx @gdd/mcp-server
```

## Configuration

### Claude Desktop

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

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

### Cursor

Add to Cursor settings (MCP configuration):

```json
{
  "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:**
```json
{
  "node_names": ["feature-a", "feature-b"],
  "max_tokens": 4000
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](../../examples/mcp-usage/) for:
- Claude Desktop configuration
- Cursor configuration
- Usage scenarios
- Expected outputs

## License

MIT