Contextflow

MCP server that connects Claude to Contextflow — semantic code search and AI-powered Q&A over vectorized repositories, directly inside Claude.

npm version license MCP Node.js

---

✨ What it does

contextflow-mcp gives Claude three native tools to interact with a Contextflow snapshot — a vectorized index of your entire codebase:

Tool	What it does
🔍 search_context	Semantic search over your codebase — finds relevant code by meaning, not keywords
🤖 ask_context	Ask any question about your code, get an AI answer grounded in real source files
📊 get_context_info	Inspect snapshot metadata: repo name, branch, files indexed, vectorized chunks

Once configured, Claude can answer questions like:

• "How does the authentication flow work?"
• "Find all places where we handle HTTP errors"
• "Is there any retry logic for failed API calls?"

…and cite the exact file and line numbers from your codebase.

---

🚀 Quick Start

Option A — npx (recommended, no install needed)

macOS / Linux:

{
  "mcpServers": {
    "contextflow": {
      "command": "npx",
      "args": ["-y", "contextflow-mcp"],
      "env": {
        "CONTEXTFLOW_TOKEN": "your_snapshot_token",
        "CONTEXTFLOW_API_URL": "https://backend2-contextflow.frogland.tech"
      }
    }
  }
}

Windows (requires cmd /c wrapper):

{
  "mcpServers": {
    "contextflow": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "contextflow-mcp"],
      "env": {
        "CONTEXTFLOW_TOKEN": "your_snapshot_token",
        "CONTEXTFLOW_API_URL": "https://backend2-contextflow.frogland.tech"
      }
    }
  }
}

Option B — Global install

npm install -g contextflow-mcp

{
  "mcpServers": {
    "contextflow": {
      "command": "contextflow-mcp",
      "args": [],
      "env": {
        "CONTEXTFLOW_TOKEN": "your_snapshot_token",
        "CONTEXTFLOW_API_URL": "https://backend2-contextflow.frogland.tech"
      }
    }
  }
}

---

⚙️ Configuration

Where to add the config

Claude client	Config file location
Claude Desktop (Mac)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code CLI	Run claude mcp add (see below)

Claude Code CLI

claude mcp add contextflow npx -- -y contextflow-mcp \
  -e CONTEXTFLOW_TOKEN=your_token \
  -e CONTEXTFLOW_API_URL=https://backend2-contextflow.frogland.tech

---

🌍 Environment Variables

Variable	Required	Default	Description
CONTEXTFLOW_TOKEN	✅ Yes	—	Public token of your Contextflow snapshot
CONTEXTFLOW_API_URL	❌ No	https://backend2-contextflow.frogland.tech	Base URL of the Contextflow API server

The server will exit immediately with a clear error message if CONTEXTFLOW_TOKEN is not set.

---

🛠️ Tools Reference

get_context_info

Returns metadata about the connected Contextflow snapshot.

No parameters required.

Example output:

Snapshot: my-backend
Branch: main
Status: ready
Files indexed: 142
Vectorized chunks: 1,847
Created: 2026-03-15T10:32:00Z

---

search_context

Performs semantic vector search over the indexed codebase.

Parameter	Type	Required	Default	Range	Description
query	string	✅ Yes	—	—	Natural language description of what to find
top_k	number	❌ No	6	1–20	Number of results to return
threshold	number	❌ No	0.45	0–1	Minimum similarity score

Example output:

Found 3 relevant fragments (87ms):

### [1] src/auth/middleware.ts (L12–45) · 92% match · typescript
export async function authMiddleware(req, res, next) {
  const token = req.cookies.session;
  ...
}

### [2] src/auth/jwt.ts (L5–28) · 78% match · typescript
...

---

ask_context

AI-powered Q&A grounded in your actual source code.

Parameter	Type	Required	Default	Range	Description
question	string	✅ Yes	—	—	Natural language question about the codebase
top_k	number	❌ No	8	3–12	Number of code chunks used as context

Example output:

The authentication system uses JWT tokens stored in HTTP-only cookies...

**Sources used:**
  1. `src/auth/middleware.ts` L12–45 (92% match)
  2. `src/config/jwt.ts` L5–20 (76% match)
  3. `src/routes/login.ts` L88–112 (71% match)

_Generated in 234ms_

---

🏗️ How it works

Claude ──(MCP stdio)──▶ contextflow-mcp ──(HTTP REST)──▶ Contextflow API
                             │                                    │
                        Validates params               Vector search + AI
                        Formats results                Returns chunks + answers

The MCP server is a lightweight adapter — it receives tool calls from Claude, proxies them to the Contextflow API using your token, and formats the results back to Claude with file paths, line numbers, and similarity scores.

---

🧑‍💻 Development

# Clone and install
git clone https://github.com/your-username/contextflow-mcp
cd contextflow-mcp
npm install

# Development (watch mode)
npm run dev

# Build
npm run build

# Run
npm start

Project structure

contextflow-mcp/
├── src/
│   └── index.ts          # MCP server source (TypeScript, 164 lines)
├── dist/
│   └── index.js          # Compiled binary (committed, ready to ship)
├── package.json
├── tsconfig.json
└── claude-config-example.json

---

📋 Requirements

• Node.js ≥ 18
• A running Contextflow instance with a valid snapshot token

---

📄 License

MIT © Miller Zamora