npm package: @gxtools/mcp
Description: gx MCP server — expose your knowledge base to AI agents via Model Context Protocol
Latest version: 0.3.0

# @gx/mcp — MCP Server for gx Knowledge Base

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps the gx API so AI coding agents (Claude Code, Cursor, Windsurf, etc.) can pull knowledge base context during tasks.

## What it does

Exposes four tools to any MCP-compatible agent:

| Tool | Description |
|---|---|
| `list_documents` | List all documents in a KB — returns `id`, `filename`, `type`, `title` |
| `get_document` | Get full content of a document (frontmatter + body) |
| `search_documents` | Client-side search across filename, title, type and frontmatter |
| `lint_document` | Run gx lint rules on raw markdown content |

## Prerequisites

- Node.js 18+
- A running gx-server instance

## Build

```bash
cd packages/gx-mcp
pnpm install
pnpm build
```

## Run

```bash
# Using defaults (Vercel-deployed server)
node dist/index.js

# With custom server
GX_SERVER_URL=http://localhost:3001 GX_API_KEY=my-key node dist/index.js

# Or via binary (after install)
gx-mcp
```

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `GX_SERVER_URL` | `https://gx-server-condorcomputing.vercel.app` | gx-server base URL |
| `GX_API_KEY` | `gx-dev-api-key` | API key (passed as `x-api-key` header) |
| `GX_KB_ID` | `78e0bc0f-38ba-4494-bcd3-416ea4532280` | Default knowledge base ID |

## Configure with Claude Desktop

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

```json
{
  "mcpServers": {
    "gx": {
      "command": "node",
      "args": ["/path/to/gx/packages/gx-mcp/dist/index.js"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_API_KEY": "gx-dev-api-key",
        "GX_KB_ID": "78e0bc0f-38ba-4494-bcd3-416ea4532280"
      }
    }
  }
}
```

Or using `npx` after publishing:

```json
{
  "mcpServers": {
    "gx": {
      "command": "npx",
      "args": ["-y", "@gx/mcp"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_API_KEY": "gx-dev-api-key"
      }
    }
  }
}
```

## Configure with Cursor

In `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "gx": {
      "command": "node",
      "args": ["/path/to/gx/packages/gx-mcp/dist/index.js"],
      "env": {
        "GX_SERVER_URL": "https://gx-server-condorcomputing.vercel.app",
        "GX_KB_ID": "78e0bc0f-38ba-4494-bcd3-416ea4532280"
      }
    }
  }
}
```

## Tool Examples

### list_documents

```json
// Input
{ "kb_id": "78e0bc0f-38ba-4494-bcd3-416ea4532280" }

// Output
[
  { "id": "abc123", "filename": "auth-decision.md", "type": "decision", "title": "Use JWT for Auth" },
  { "id": "def456", "filename": "onboarding.md", "type": "guide", "title": "Getting Started" }
]
```

### get_document

```json
// Input
{ "document_id": "abc123" }

// Output
{
  "id": "abc123",
  "filename": "auth-decision.md",
  "type": "decision",
  "title": "Use JWT for Auth",
  "frontmatter": { "type": "decision", "title": "Use JWT for Auth", "status": "accepted" },
  "content": "---\ntype: decision\n...\n\n# Use JWT for Auth\n\n..."
}
```

### search_documents

```json
// Input
{ "kb_id": "78e0bc0f-...", "query": "auth", "type": "decision" }

// Output
[
  { "id": "abc123", "filename": "auth-decision.md", "type": "decision", "title": "Use JWT for Auth" }
]
```

### lint_document

```json
// Input
{ "content": "# My Doc\n\nSome content without frontmatter" }

// Output
[
  { "ruleId": "GX001", "severity": "error", "message": "Missing frontmatter", "line": null }
]
```