@codehabits/mcp

MCP server for codehabits team intelligence. Expose your repository’s conventions, anti-patterns, and domain knowledge to AI coding agents through the Model Context Protocol.

Works with Cursor, Claude Code, and other MCP-capable clients. Pair with @codehabits/cli to generate .codehabits/ from PR history.

• Website: codehabits.dev
• Docs: codehabits.dev/docs
• CLI (generate intelligence): @codehabits/cli

Prerequisites

1. Node.js 20+
2. Intelligence files in the project root (run once per repo):

npx @codehabits/cli login
npx @codehabits/cli enable

The MCP server reads .codehabits/ from the process working directory (cwd). It reloads when intelligence files change on disk.

Quick install (Cursor)

From your repository root (after enable):

npx @codehabits/cli mcp-install

This writes .cursor/mcp.json (or ~/.cursor/mcp.json with --global):

{
  "mcpServers": {
    "codehabits": {
      "command": "npx",
      "args": ["@codehabits/mcp"],
      "cwd": "/absolute/path/to/your/repo"
    }
  }
}

Restart the IDE so the server loads.

Manual MCP configuration

Use the same shape anywhere MCP stdio servers are supported. Important: set cwd to the repo that contains .codehabits/.

Cursor (project)

Path: .cursor/mcp.json

{
  "mcpServers": {
    "codehabits": {
      "command": "npx",
      "args": ["-y", "@codehabits/mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Claude Code (example)

Add to your Claude MCP config (path varies by install):

{
  "mcpServers": {
    "codehabits": {
      "command": "npx",
      "args": ["-y", "@codehabits/mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Run directly (debug)

cd /path/to/your/repo
npx @codehabits/mcp

Stdio transport only; intended for IDE integration, not HTTP.

Tools

| Tool | Description | | --- | --- | | get_team_context | Conventions, anti-patterns, and knowledge; optionally filtered by scope or file_path | | check_code | Validate a code snippet against team rules; returns violations and suggestions | | get_knowledge | Look up a domain topic (e.g. authentication, database, deployment) | | suggest_reviewers | Rank reviewers for a list of changed file paths | | record_feedback | Propose a convention change or correction (writes local proposals.json, gitignored) | | approve_proposal | Merge an approved proposal into tracked intelligence and regenerate skills |

get_team_context

Use before writing or reviewing code.

| Parameter | Type | Description | | --- | --- | --- | | scope | enum (optional) | all, imports, testing, naming, async, api, auth, database, structure, error-handling, documentation, security, performance, type-safety | | file_path | string (optional) | Tailor context to a file type or path |

check_code

| Parameter | Type | Description | | --- | --- | --- | | code | string | Snippet to validate | | file_path | string (optional) | Path for context-aware rules |

get_knowledge

| Parameter | Type | Description | | --- | --- | --- | | topic | string | Topic name (fuzzy match supported) |

suggest_reviewers

| Parameter | Type | Description | | --- | --- | --- | | files | string[] | Changed file paths |

record_feedback / approve_proposal

Agents can suggest updates when the user overrides team rules:

1. record_feedback stores a proposal in .codehabits/proposals.json (not committed by default).
2. Human reviews, then approve_proposal with proposal_id updates conventions.json and regenerates skill markdown / AGENTS.md (creates normal git changes to commit).

| record_feedback field | Description | | --- | --- | | type | new_convention, update_convention, new_exception, deprecate | | targetId | Existing convention id (for update/exception/deprecate) | | rule | Rule text (new conventions) | | reason | Why the change is proposed | | category | e.g. testing, naming | | file_path | Where the issue appeared |

Example agent workflows

Before implementing a feature

Call get_team_context with scope: "api" or file_path set to the file you are editing.

During review

Call check_code on the diff snippet; fix violations the tool reports.

When the model disagrees with a convention

Call record_feedback with type: "new_exception" and a clear reason; a teammate runs approve_proposal after review.

PR assignment

Call suggest_reviewers with the list of changed paths.

How it works

sequenceDiagram
  participant IDE as IDE / Agent
  participant MCP as @codehabits/mcp
  participant FS as .codehabits/*.json
  IDE->>MCP: tools/call (stdio)
  MCP->>FS: read + watch
  FS-->>MCP: IntelligenceFile
  MCP-->>IDE: conventions / violations / knowledge

• Transport: MCP over stdio (@modelcontextprotocol/sdk).
• State: Loaded from disk; no separate database.
• Hot reload: File watcher updates in-memory intelligence when JSON changes (e.g. after codehabits sync).

If intelligence is missing, tools return a message asking you to run codehabits enable first.

Passive vs active intelligence

| Mechanism | Package | When agents use it | | --- | --- | --- | | AGENTS.md + .claude/skills/ + .agents/skills/ | CLI enable | Automatically in context / skill discovery | | MCP tools (this package) | @codehabits/mcp | On demand during chat or agent loops |

Use both: skills for always-on team voice; MCP for lookups, checks, and structured feedback.

Troubleshooting

| Symptom | Fix | | --- | --- | | “No intelligence data available” | Run npx @codehabits/cli enable in the repo; confirm .codehabits/meta.json exists | | Tools return stale rules | Run npx @codehabits/cli sync; restart IDE if the watcher did not fire | | Server starts but wrong conventions | Check MCP cwd points at the repo root, not a subfolder | | npx fails in IDE | Use full path to codehabits-mcp or pin version: npx -y @codehabits/[email protected] |

Verify integration:

npx @codehabits/cli status

Related packages

| Package | Role | | --- | --- | | @codehabits/cli | Login, enable, sync, mcp-install, CI tokens |

License

MIT © codehabits