smart-coding-mcp

A stateful coding-analysis MCP server that gives your AI coding assistant persistent memory, deterministic code checks, and a curated rules file that grows with your project.

Quick start (30 seconds)

If you just want to see it work:

uvx smart-coding-mcp doctor

That downloads the package from PyPI, runs the diagnostic in an ephemeral Python env, and prints a report. If you see [ok] lines, you're set up.

To wire it into your editor (Kimi Code, Claude Code, Cursor, anything MCP-aware), save the snippet below to the path your editor reads:

{
  "mcpServers": {
    "smart-agent": {
      "command": "uvx",
      "args": ["smart-coding-mcp"]
    }
  }
}

Start a new session. The orchestrator will start using the lesson store automatically; there's nothing else to wire up.

If anything fails, jump to Troubleshooting.

Related MCP server: CodeImpact

What is this?

A stateful coding-analysis MCP specialist for the Kimi Code (and Claude Code / Cursor / any MCP-aware orchestrator) agent loop. It holds a persistent lesson store, runs deterministic static checks the LLM shouldn't be trusted with, and helps a project evolve a curated rules file (AGENTS.md) over time.

The agent itself does not call any LLM. Every "intelligence" call comes from the orchestrator. Its job is to:

1. Hold persistent state across sessions.

2. Run deterministic checks the LLM can't be trusted with.

3. Make past lessons trivially retrievable so the orchestrator applies them.

That's what "evolution" looks like today: persistent lessons + an orchestrator that follows the recall-at-start / record-at-end convention (see § Convention).

Install

Three ways — pick the one that fits.

1. From PyPI (recommended for users)

The package is on PyPI as smart-coding-mcp. You can run it ephemerally (uvx) or install it persistently (pip / uv add).

Run without installing — uvx pulls the latest published wheel into a throwaway env, runs the command, then discards the env:

uvx smart-coding-mcp                # start the MCP server (default subcommand)
uvx smart-coding-mcp doctor         # one-shot diagnostic
uvx smart-coding-mcp --help         # list subcommands

Install into your current Python env:

pip install smart-coding-mcp            # runtime only
pip install "smart-coding-mcp[dev]"     # also installs pytest + ruff

Cross-platform: works on Linux, macOS, and Windows. Python 3.10+ required.

⚠️ Important name note. Always type smart-coding-mcp (with the -mcp suffix). PyPI hosts another package called smart-agent owned by someone else; uvx smart-agent doctor resolves to that one and crashes with ModuleNotFoundError: readline on Windows. See Troubleshooting.

2. From source (for active development)

Use this when you want to modify the code.

git clone https://github.com/cbuntingde/smart-agent
cd smart-agent
uv sync
uv run smart-coding-mcp                # == uv run smart-coding-mcp serve
uv run smart-coding-mcp doctor

Edits land in the next session without re-installing.

3. Local-path wiring (when running from a working tree)

Same as option 2, but Kimi Code's mcp.json points directly at the working tree so any unsaved changes are live:

{
  "mcpServers": {
    "smart-agent": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/smart-agent",
        "run", "smart-coding-mcp"
      ]
    }
  }
}

In all three paths the entry point is the same: smart-coding-mcp, with subcommands serve (default), doctor, --help.

Wire into your editor

smart-coding-mcp speaks the Model Context Protocol over stdio. Any MCP-aware client can use it.

Kimi Code

~/.kimi-code/mcp.json:

{
  "mcpServers": {
    "smart-agent": {
      "command": "uvx",
      "args": ["smart-coding-mcp"]
    }
  }
}

Claude Code

claude mcp add --transport stdio smart-coding-mcp -- uvx smart-coding-mcp

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "smart-coding-mcp": {
      "command": "uvx",
      "args": ["smart-coding-mcp"]
    }
  }
}

Claude Desktop / Web

Streamable HTTP isn't directly supported in the connector UI. Wrap the stdio server with mcp-remote:

npm install -g mcp-remote

Then in Claude Desktop's custom connector config:

{
  "smart-coding-mcp": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://search.parallel.ai/mcp"]
  }
}

Replace smart-coding-mcp endpoint accordingly — Claude Desktop's connector dialog accepts the mcp-remote --stdio uvx ... wrapper if you point it at a stdio script.

Verify it works

uvx smart-coding-mcp doctor

If you see [ok] lines for paths, DB, and store stats — and your editor's mcp.json is in place — you're done.

What you get

The orchestrator's LLM does the reasoning. This agent is the stateful, deterministic scaffolding around it.

Platforms

Python 3.10, 3.11, 3.12, 3.13 all tested.

Production readiness

Architecture

See ARCHITECTURE.md for a deeper dive (module map, data flow diagram, schema versioning protocol, logging conventions, configuration env vars, what-it-doesn't list).

In one sentence: the orchestrator talks to this server via MCP; the server holds a SQLite store and an AGENTS.md file; the server never calls an LLM.

Tools

14 MCP tools, organised by what they do:

Plus three resources (memory://recent, memory://stats, conventions://current) and one prompt (code_review). Full list: ARCHITECTURE.md.

Convention: recall-at-start / record-at-end

The agent gets smarter only if the orchestrator follows this discipline:

BEFORE tackling a task:
   1. Call recall_lessons(query=task_topic, k=5)
   2. Read conventions://current
   3. Apply each relevant rule before flagging it as a new finding

AFTER each non-trivial task (or whenever you learn something reusable):
   1. Call record_lesson(category, summary, evidence, tags)
      — keep summary atomic (~80 chars)
      — category ∈ bug, style, perf, convention, debt, risky, win
      — tags comma-separated, no spaces within tags
   2. If the lesson is project-wide, also call set_convention(...)
      — plain English, 1-3 sentences

The MCP server's instructions field repeats this so any MCP-aware orchestrator gets the reminder at session start.

What's possible — and what isn't

The agent doesn't try to do the impossible — it does the things that actually compose to "smarter over time": lessons persist, the orchestrator applies them, the orchestrator records new ones, the conventions file grows.

Caveats — known limits

Honest list of what's still imperfect as of v0.2.x:

• Multi-user / shared AGENTS.md. Every entry is appended; no merge logic or ownership tracking. Treat as single-author.

• Prompt injection. Convention text ends up in the orchestrator's context (the orchestrator decides how — this server doesn't write to LLM prompts directly). Treat AGENTS.md like any user-supplied file that ends up in an LLM prompt.

• Large codebases. analyze_path walks the FS with a default cap of 5 000 files and skips files > 1 MB. Pass focus="risk" for huge codebases.

• Concurrency. Single-process SQLite. Multi-writer contention is rare in practice but possible if you point several long-lived MCP servers at the same DB file.

Found a sharp edge? Open an issue or fix it inline and PR — the code is short on purpose. See CONTRIBUTING.md.

Troubleshooting

Storage

Override the data dir with SMART_AGENT_HOME=/path/to/dir.

Run diagnostics

uvx smart-coding-mcp doctor

Validates paths, DB integrity, linter availability, and store contents. Exit 0 = OK; 1 = a hard error. WARN lines don't fail the doctor.

Equivalent MCP tool (callable from a running session): doctor_tool() returns the same report as a string.

Tests

uv run pytest            # in the source tree

55 tests across tests/test_{store,analyzer,server,server_new,lint, reflector,doctor,cli}.py. There's also a real-subprocess stdio handshake verifier:

uv run python smoke_stdio.py

The CI matrix in .github/workflows/ci.yml runs both, plus uv build and twine check, on Linux, macOS, and Windows against Python 3.10–3.13.

Contributing

PRs welcome. See CONTRIBUTING.md for dev setup, PR checklist, and release process. Security issues: see SECURITY.md.

Roadmap

• Semantic recall via sqlite-vec (embedding-based search for >10k lessons)

• Per-project isolation (multi-tenant the SQLite by project_root)

• reflect worker that proposes a new AGENTS.md draft as a separate, optional tool

• DSPy GEPA / MIPROv2 offline prompt optimisation against measured "what worked / didn't" sets

License

MIT — see LICENSE. © 2026 cbunt.