@codehabits/mcp

@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

• Node.js 20+
• 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:

• record_feedback stores a proposal in .codehabits/proposals.json (not committed by default).
• 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/mcp@0.1.1

Verify integration:

npx @codehabits/cli status

Related packages

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

License

MIT © codehabits