Metadata-Version: 2.4
Name: smart-coding-mcp
Version: 0.3.0
Summary: A stateful coding-analysis MCP specialist — persistent lesson store, deterministic checks, evolving AGENTS.md.
Project-URL: Homepage, https://github.com/cbuntingde/smart-agent
Project-URL: Repository, https://github.com/cbuntingde/smart-agent.git
Project-URL: Issues, https://github.com/cbuntingde/smart-agent/issues
Project-URL: Changelog, https://github.com/cbuntingde/smart-agent/releases
Author: cbunt
License-Expression: MIT
License-File: LICENSE
Keywords: agent,code-analysis,lint,mcp,memory,model-context-protocol,reflection,self-improving,static-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: fastmcp<4.0,>=3.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# 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](#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:

```bash
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:

```json
{
  "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](#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](#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](#convention-recall-at-start--record-at-end)).

---

## 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:

```bash
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:**

```bash
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](#troubleshooting).

### 2. From source *(for active development)*

Use this when you want to modify the code.

```bash
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:

```json
{
  "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][mcp] over stdio.
Any MCP-aware client can use it.

[mcp]: https://modelcontextprotocol.io/

### Kimi Code

`~/.kimi-code/mcp.json`:

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

### Claude Code

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

### Cursor

`~/.cursor/mcp.json`:

```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`:

```bash
npm install -g mcp-remote
```

Then in Claude Desktop's custom connector config:

```json
{
  "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

```bash
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`](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`](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`](ARCHITECTURE.md).

---

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

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

```text
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`](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](#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

```bash
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

```bash
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:

```bash
uv run python smoke_stdio.py
```

The CI matrix in [`.github/workflows/ci.yml`](.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`](CONTRIBUTING.md) for dev setup,
PR checklist, and release process. Security issues: see
[`SECURITY.md`](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`](LICENSE). © 2026 cbunt.
