smart-coding-mcp 0.3.0

A stateful coding-analysis MCP specialist — persistent lesson store, deterministic checks, evolving AGENTS.md.

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.

Try it	uvx smart-coding-mcp doctor
Wire it up	drop the JSON in § Wire into your editor into your editor's mcp.json
Status	v0.2.x · Beta · 55 tests green · CI on Linux / macOS / Windows
License	MIT

---

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"]
    }
  }
}

Editor	Config file
Kimi Code	~/.kimi-code/mcp.json
Claude Code	claude mcp add --transport stdio smart-coding-mcp -- uvx smart-coding-mcp
Cursor	~/.cursor/mcp.json
Claude Desktop	use mcp-remote over HTTP — see Wire into your editor

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.

---

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

Capability	How
Persistent memory across sessions	SQLite + FTS5 lesson store at ~/.local/share/smart-agent/store.db (POSIX) or %LOCALAPPDATA%/smart-agent/store.db (Windows). Override with $SMART_AGENT_HOME.
Deterministic static analysis	analyze_path — long functions, bare except:, TODO/FIXME, long lines, oversized files.
Subprocess linters and tests	lint_check runs ruff and/or pytest as subprocesses; gracefully skips missing binaries.
Living conventions file	AGENTS.md that the orchestrator curates.
Recall-at-start / record-at-end loop	recall_lessons(query, k=5) at task start; record_lesson(...) after.

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

---

Platforms

Platform	Tested in CI
Linux (Ubuntu)	✅
macOS	✅
Windows	✅

Python 3.10, 3.11, 3.12, 3.13 all tested.

---

Production readiness

Concern	Where
Schema evolution	_meta table tracks schema_version; _run_migrations() applies pending upgrades on open.
Crash safety	Per-operation SQLite connections (no shared long-lived handle). WAL + synchronous=NORMAL.
Logging	stdlib logging to stderr (MCP owns stdout). Level via $SMART_AGENT_LOG_LEVEL or $LOG_LEVEL.
Monitoring	health_check MCP tool returns JSON for monitoring / liveness.
Input validation	All tool params go through FastMCP's Pydantic schema; the store enforces caps on summary (500), evidence (2 000), tag count (32), tag CSV length (500).
Security	See SECURITY.md. Subprocess tools spawn via shutil.which only — no shell interpretation.
Reproducibility	uv.lock is committed; CI installs the exact pinned tree.

---

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:

Purpose	Tools
Memory — write	record_lesson, mark_lesson_used
Memory — read	recall_lessons, recent_lessons, by_category, propose_fix
Conventions	get_conventions, set_convention
Static analysis	analyze_path, lint_check, reflect
Diagnostics	health_check, store_stats, doctor_tool

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

Goal	Status
Persistent memory across sessions	✅ SQLite + FTS5 lesson store
Deterministic static analysis	✅ built-in
Subprocess linters and tests	✅ lint_check
Living conventions file	✅ AGENTS.md
Recall-at-start / record-at-end loop	✅
Code self-modification of the agent itself	❌ not shipping in any production tool
Online weight learning	❌ not production-stable
True evolutionary self-improvement	❌ research-only

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

Symptom	Likely cause	Fix
uvx smart-agent doctor (without -mcp) crashes with ModuleNotFoundError: readline	PyPI has another smart-agent package (Don Kang's MCP chatbot). Our distribution is smart-coding-mcp — the name matters.	Use uvx smart-coding-mcp doctor.
ModuleNotFoundError: smart_agent after pip install	The other smart-agent package was installed by mistake.	pip uninstall smart-agent (the impostor); pip install smart-coding-mcp.
MCP server "smart-agent" failed: Access is denied … smart-agent.exe after editing the source	mcp.json is using local-path uv run, which triggers re-sync on every launch. The freshly built smart-coding-mcp.exe collides with the still-running one.	Switch the entry to command: uvx, args: ["smart-coding-mcp"] — see § Wire into your editor.
MCP server "smart-agent" failed: … smart-coding-mcp is not provided by package smart-coding-mcp	You typed args: ["smart-coding-mcp"] and old mcp.json had --from smart-coding-mcp smart-agent. Either is fine, but mixing them causes this error.	Pick one form: bare args: ["smart-coding-mcp"] works in v0.2.1+.
lint_check reports ruff NOT on PATH	Optional — ruff isn't a hard requirement.	pip install "smart-coding-mcp[dev]" or uv add --dev ruff.
FileNotFoundError: AGENTS.md when first reading get_conventions	The conventions file is created lazily on first set_convention call.	Expected — call set_convention("…") to create it.
Permission errors on Windows when running tests via uv run	The previous smart-coding-mcp.exe is still held by an MCP server; uv sync can't overwrite.	uv run --no-sync for tests, or close the active Kimi session.

---

Storage

Path	Purpose
~/.local/share/smart-agent/store.db (POSIX)	SQLite DB
%LOCALAPPDATA%/smart-agent/store.db (Win)	SQLite DB
<project>/AGENTS.md	Curated conventions file (track in git!)

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.