smart-agent-mcp 0.1.0__tar.gz

smart_agent_mcp-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# --- Python ------------------------------------------------------------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+*.egg-info/
+
+# --- Test / lint caches ------------------------------------------------
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# --- Virtual environments ---------------------------------------------
+.venv/
+venv/
+env/
+ENV/
+
+# --- IDE / OS ---------------------------------------------------------
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# --- uv ----------------------------------------------------------------
+# `uv.lock` is intentionally tracked: smart-agent is an installed
+# tool, not a library; pinning ensures the same versions run across
+# environments. Drop it from the repo if you'd rather not.
+
+# --- Smart-agent runtime ----------------------------------------------
+# The SQLite store lives at:
+#   %LOCALAPPDATA%/smart-agent/store.db   (Windows)
+#   $XDG_DATA_HOME/smart-agent/store.db   (POSIX)
+# and is per-user, not per-project — already outside the working tree.
+
+# `AGENTS.md` is the project-curated convention file. The default
+# `Config.load()` writes to `<project_root>/AGENTS.md`. Track it if
+# you want shared conventions; ignore it for personal-only state.

smart_agent_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cbunt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smart_agent_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: smart-agent-mcp
+Version: 0.1.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 :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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-agent
+
+> ## ⚠️ Prototype / unvalidated idea — not production-tested
+>
+> This project exists to explore whether a "smart, self-evolving coding agent"
+> is buildable with today's MCP + LLM tooling. It was assembled as a single
+> focused session from a research scan, not from a backlog of real-world use.
+>
+> **What's been tested:** unit tests pass (44), a local stdio handshake with
+> FastMCP works, and the doctor CLI runs. **What's *not* been tested:**
+> extended use inside Kimi Code (or any other orchestrator), production data
+> volumes, permission boundaries, scale of the lesson store, multi-session
+> behaviour, conflicts with the rest of the user's MCP servers.
+>
+> Treat this as a **design probe**, not a finished product. The architecture
+> and code are deliberately simple so they can be read, modified, and either
+> proven-out or thrown away. Don't ship it to anyone else until you've actually
+> used it yourself for a while.
+
+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.
+
+## What's possible today — and what isn't
+
+| Goal | Status |
+|---|---|
+| Persistent memory across sessions | ✅ SQLite + FTS5 lesson store |
+| Deterministic static analysis | ✅ `analyze_path` (long fns, bare `except:`, TODO/FIXME, long lines, oversized files) |
+| Living conventions file | ✅ `AGENTS.md` that the orchestrator appends to |
+| Recall-at-start / record-at-end loop | ✅ via `recall_lessons` + `record_lesson` |
+| 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 |
+
+This agent doesn't try to do the impossible — it does the things that *actually* compose to "smarter over time":
+
+1. **Lessons persist** across sessions (SQLite + FTS5 — semantic retrieval without an embedding model).
+2. **The orchestrator applies them** via `recall_lessons` at task start.
+3. **The orchestrator records new ones** via `record_lesson` after each task.
+4. **The conventions file grows** as `set_convention` is called.
+
+The orchestrator's LLM is the "reasoning" component. This agent is the **stateful, deterministic scaffolding around it**.
+
+## Architecture
+
+```
+┌─────────────────────────────┐
+│  Main AI agent (Kimi Code)  │   ← does reasoning, talks to user
+│  LLM / tool-calling loop    │
+└─────────────┬───────────────┘
+              │ MCP / stdio
+              ▼
+┌─────────────────────────────┐
+│  smart-agent (this server)  │
+│                             │
+│  Tools:                     │
+│   analyze_path  ▶ findings  │
+│   record_lesson ▶ insert    │
+│   recall_lessons▶ search    │
+│   recent_lessons▶ tail      │
+│   mark_lesson_used ▶ bump   │  ───┐
+│   get_conventions           │     │
+│   set_convention            │     │ SQLite + FTS5
+│   propose_fix               │  ───┤ lessons table
+│   store_stats               │     │ (WAL mode)
+│                             │     │
+│  Resources:                 │     ▼
+│   memory://recent    ◀──── │  ┌────────────────────┐
+│   memory://stats     ◀──── │  │ store.db (FTS5)    │
+│   conventions://current    │  └────────────────────┘
+└─────────────────────────────┘            │
+              │                            │
+              ▼                            ▼
+       ┌─────────────┐              ┌─────────────┐
+       │  AGENTS.md  │              │  SQLite DB  │
+       │ (curated    │              │ ~/.local/   │
+       │  rules)     │              │  share/...  │
+       └─────────────┘              └─────────────┘
+```
+
+The agent itself has **no LLM call**. Every "intelligence" is the orchestrator's, mediated through deterministic tools.
+
+## Caveats before you read further
+
+This was assembled quickly and the goal was *to learn what such an agent
+looks like*, not to ship a stable product. Specific things I have **not**
+verified:
+
+- **Behaviour as a real `mcp.json` server** in your daily Kimi Code sessions.
+  Only the `smoke_stdio.py` handshake has run, in isolation.
+- **Tool-runtime edge cases** beyond what the unit tests cover: very large
+  codebases for `analyze_path`, pathological FTS5 inputs, store with >1k
+  lessons.
+- **Multi-user / shared-`AGENTS.md` semantics.** Today every entry is just
+  appended; there is no merge logic or ownership tracking.
+- **Prompt injection.** Convention text from this file is *not* fed back
+  into any LLM prompt by this server directly, but the orchestrator may
+  include it in its own context. Treat `AGENTS.md` like you treat any
+  other user-supplied file that ends up in an LLM prompt.
+- **Concurrency.** The SQLite store is single-process; if you ever wire it
+  up so multiple sessions hit the same DB file, expect WAL contention.
+- **The "evolution" claim.** The agent *accumulates* knowledge and
+  *suggests* conventions — whether that becomes a meaningfully better
+  coding agent over weeks of use is an open question. Use it long enough
+  to find out, or don't.
+
+If you find a bug, file it as an issue or fix it inline and learn from
+the patch — the code is short on purpose.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `analyze_path(path, focus, max_files)` | Run built-in static checks; returns Markdown report + raw findings. |
+| `lint_check(path, runs, timeout_seconds)` | Run `ruff` and/or `pytest` as subprocesses; returns findings in the same shape, with `source="ruff"`/`"pytest"`. Tools not on PATH are skipped. |
+| `record_lesson(category, summary, evidence, tags)` | Persist an atomic lesson. Categories: `bug`, `style`, `perf`, `convention`, `debt`, `risky`, `win`. |
+| `recall_lessons(query, k)` | Retrieve top-k lessons by FTS5 match. Empty query → recent. |
+| `recent_lessons(limit)` | Chronological tail. |
+| `by_category(category, limit)` | All lessons for a category. |
+| `mark_lesson_used(lesson_id)` | Bump `times_used` when the orchestrator actually applied a lesson. |
+| `get_conventions()` | Read the project's `AGENTS.md`. |
+| `set_convention(text)` | Append a bullet to `AGENTS.md`. |
+| `propose_fix(issue_summary, k)` | Stitch a fix sketch from past lessons. |
+| `reflect(lookback_n, min_count, dry_run)` | Return a Markdown draft of new conventions from recent lessons. **Always non-destructive** — orchestrator decides which lines to apply via `set_convention`. |
+| `store_stats()` | Total + per-category counts. |
+| `doctor_tool()` | Same report as `smart-agent doctor` CLI, returned as a string. |
+
+### Resources
+
+| URI | Content |
+|---|---|
+| `memory://recent` | Last 20 lessons (Markdown). |
+| `memory://stats` | Total + per-category counts. |
+| `conventions://current` | Full `AGENTS.md` content. |
+
+### Prompt
+
+- `code_review(diff, focus)` — structured prompt that asks the orchestrator to start by recalling lessons and conventions before reviewing.
+
+## Convention: recall-at-start / record-at-end
+
+Smart agents get 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 must be one of: 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(...)
+      - Use plain English, 1-3 sentences
+```
+
+The MCP server's `instructions` field repeats this so any MCP-aware orchestrator gets the reminder at session start.
+
+## 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 the server
+
+```bash
+uv sync
+uv run smart-agent            # stdio transport (== `smart-agent serve`)
+```
+
+## Run diagnostics
+
+```bash
+uv run smart-agent doctor
+```
+
+Validates paths, DB integrity, linter availability, and store contents. Exit code 0 = OK; 1 = a hard error (DB unreadable, store corrupt). WARN lines (linters missing, conventions file absent) don't fail the doctor.
+
+## Wire it into Kimi Code CLI
+
+`~/.kimi-code/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "smart-agent": {
+      "command": "uv",
+      "args": ["--directory", "C:/az-mcpservers/smart-agent", "run", "smart-agent"]
+    }
+  }
+}
+```
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+44 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 test suite uses the FastMCP in-memory `Client` (`from fastmcp import Client`) so the full MCP protocol path is exercised without spawning subprocesses.
+
+## Roadmap
+
+Things to add when this first version needs more muscle:
+
+1. **Semantic recall.** Replace FTS5 with `sqlite-vec` for embedding-based search when >10k lessons pile up.
+2. **Reflection worker.** Add a `reflect(lookback_n=50)` tool that returns a summary of recent lessons grouped by category — the orchestrator reads it and proposes a new `AGENTS.md` draft. Already half-built (`propose_fix` does the pattern-match half).
+3. **Per-check tooling.** Compose with Ruff/mypy/pytest via subprocess and feed results into the same `Finding` shape.
+4. **DSPy offline optimization.** Once you have a labelled "what worked / didn't" set, run GEPA/MIPROv2 against this agent's prompts as a batch job.
+5. **Project isolation.** Multi-tenant the SQLite by `project_root` so a monorepo can keep per-package lessons.
+
+## License
+
+MIT.

smart_agent_mcp-0.1.0/README.md

@@ -0,0 +1,228 @@
+# smart-agent
+
+> ## ⚠️ Prototype / unvalidated idea — not production-tested
+>
+> This project exists to explore whether a "smart, self-evolving coding agent"
+> is buildable with today's MCP + LLM tooling. It was assembled as a single
+> focused session from a research scan, not from a backlog of real-world use.
+>
+> **What's been tested:** unit tests pass (44), a local stdio handshake with
+> FastMCP works, and the doctor CLI runs. **What's *not* been tested:**
+> extended use inside Kimi Code (or any other orchestrator), production data
+> volumes, permission boundaries, scale of the lesson store, multi-session
+> behaviour, conflicts with the rest of the user's MCP servers.
+>
+> Treat this as a **design probe**, not a finished product. The architecture
+> and code are deliberately simple so they can be read, modified, and either
+> proven-out or thrown away. Don't ship it to anyone else until you've actually
+> used it yourself for a while.
+
+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.
+
+## What's possible today — and what isn't
+
+| Goal | Status |
+|---|---|
+| Persistent memory across sessions | ✅ SQLite + FTS5 lesson store |
+| Deterministic static analysis | ✅ `analyze_path` (long fns, bare `except:`, TODO/FIXME, long lines, oversized files) |
+| Living conventions file | ✅ `AGENTS.md` that the orchestrator appends to |
+| Recall-at-start / record-at-end loop | ✅ via `recall_lessons` + `record_lesson` |
+| 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 |
+
+This agent doesn't try to do the impossible — it does the things that *actually* compose to "smarter over time":
+
+1. **Lessons persist** across sessions (SQLite + FTS5 — semantic retrieval without an embedding model).
+2. **The orchestrator applies them** via `recall_lessons` at task start.
+3. **The orchestrator records new ones** via `record_lesson` after each task.
+4. **The conventions file grows** as `set_convention` is called.
+
+The orchestrator's LLM is the "reasoning" component. This agent is the **stateful, deterministic scaffolding around it**.
+
+## Architecture
+
+```
+┌─────────────────────────────┐
+│  Main AI agent (Kimi Code)  │   ← does reasoning, talks to user
+│  LLM / tool-calling loop    │
+└─────────────┬───────────────┘
+              │ MCP / stdio
+              ▼
+┌─────────────────────────────┐
+│  smart-agent (this server)  │
+│                             │
+│  Tools:                     │
+│   analyze_path  ▶ findings  │
+│   record_lesson ▶ insert    │
+│   recall_lessons▶ search    │
+│   recent_lessons▶ tail      │
+│   mark_lesson_used ▶ bump   │  ───┐
+│   get_conventions           │     │
+│   set_convention            │     │ SQLite + FTS5
+│   propose_fix               │  ───┤ lessons table
+│   store_stats               │     │ (WAL mode)
+│                             │     │
+│  Resources:                 │     ▼
+│   memory://recent    ◀──── │  ┌────────────────────┐
+│   memory://stats     ◀──── │  │ store.db (FTS5)    │
+│   conventions://current    │  └────────────────────┘
+└─────────────────────────────┘            │
+              │                            │
+              ▼                            ▼
+       ┌─────────────┐              ┌─────────────┐
+       │  AGENTS.md  │              │  SQLite DB  │
+       │ (curated    │              │ ~/.local/   │
+       │  rules)     │              │  share/...  │
+       └─────────────┘              └─────────────┘
+```
+
+The agent itself has **no LLM call**. Every "intelligence" is the orchestrator's, mediated through deterministic tools.
+
+## Caveats before you read further
+
+This was assembled quickly and the goal was *to learn what such an agent
+looks like*, not to ship a stable product. Specific things I have **not**
+verified:
+
+- **Behaviour as a real `mcp.json` server** in your daily Kimi Code sessions.
+  Only the `smoke_stdio.py` handshake has run, in isolation.
+- **Tool-runtime edge cases** beyond what the unit tests cover: very large
+  codebases for `analyze_path`, pathological FTS5 inputs, store with >1k
+  lessons.
+- **Multi-user / shared-`AGENTS.md` semantics.** Today every entry is just
+  appended; there is no merge logic or ownership tracking.
+- **Prompt injection.** Convention text from this file is *not* fed back
+  into any LLM prompt by this server directly, but the orchestrator may
+  include it in its own context. Treat `AGENTS.md` like you treat any
+  other user-supplied file that ends up in an LLM prompt.
+- **Concurrency.** The SQLite store is single-process; if you ever wire it
+  up so multiple sessions hit the same DB file, expect WAL contention.
+- **The "evolution" claim.** The agent *accumulates* knowledge and
+  *suggests* conventions — whether that becomes a meaningfully better
+  coding agent over weeks of use is an open question. Use it long enough
+  to find out, or don't.
+
+If you find a bug, file it as an issue or fix it inline and learn from
+the patch — the code is short on purpose.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `analyze_path(path, focus, max_files)` | Run built-in static checks; returns Markdown report + raw findings. |
+| `lint_check(path, runs, timeout_seconds)` | Run `ruff` and/or `pytest` as subprocesses; returns findings in the same shape, with `source="ruff"`/`"pytest"`. Tools not on PATH are skipped. |
+| `record_lesson(category, summary, evidence, tags)` | Persist an atomic lesson. Categories: `bug`, `style`, `perf`, `convention`, `debt`, `risky`, `win`. |
+| `recall_lessons(query, k)` | Retrieve top-k lessons by FTS5 match. Empty query → recent. |
+| `recent_lessons(limit)` | Chronological tail. |
+| `by_category(category, limit)` | All lessons for a category. |
+| `mark_lesson_used(lesson_id)` | Bump `times_used` when the orchestrator actually applied a lesson. |
+| `get_conventions()` | Read the project's `AGENTS.md`. |
+| `set_convention(text)` | Append a bullet to `AGENTS.md`. |
+| `propose_fix(issue_summary, k)` | Stitch a fix sketch from past lessons. |
+| `reflect(lookback_n, min_count, dry_run)` | Return a Markdown draft of new conventions from recent lessons. **Always non-destructive** — orchestrator decides which lines to apply via `set_convention`. |
+| `store_stats()` | Total + per-category counts. |
+| `doctor_tool()` | Same report as `smart-agent doctor` CLI, returned as a string. |
+
+### Resources
+
+| URI | Content |
+|---|---|
+| `memory://recent` | Last 20 lessons (Markdown). |
+| `memory://stats` | Total + per-category counts. |
+| `conventions://current` | Full `AGENTS.md` content. |
+
+### Prompt
+
+- `code_review(diff, focus)` — structured prompt that asks the orchestrator to start by recalling lessons and conventions before reviewing.
+
+## Convention: recall-at-start / record-at-end
+
+Smart agents get 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 must be one of: 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(...)
+      - Use plain English, 1-3 sentences
+```
+
+The MCP server's `instructions` field repeats this so any MCP-aware orchestrator gets the reminder at session start.
+
+## 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 the server
+
+```bash
+uv sync
+uv run smart-agent            # stdio transport (== `smart-agent serve`)
+```
+
+## Run diagnostics
+
+```bash
+uv run smart-agent doctor
+```
+
+Validates paths, DB integrity, linter availability, and store contents. Exit code 0 = OK; 1 = a hard error (DB unreadable, store corrupt). WARN lines (linters missing, conventions file absent) don't fail the doctor.
+
+## Wire it into Kimi Code CLI
+
+`~/.kimi-code/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "smart-agent": {
+      "command": "uv",
+      "args": ["--directory", "C:/az-mcpservers/smart-agent", "run", "smart-agent"]
+    }
+  }
+}
+```
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+44 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 test suite uses the FastMCP in-memory `Client` (`from fastmcp import Client`) so the full MCP protocol path is exercised without spawning subprocesses.
+
+## Roadmap
+
+Things to add when this first version needs more muscle:
+
+1. **Semantic recall.** Replace FTS5 with `sqlite-vec` for embedding-based search when >10k lessons pile up.
+2. **Reflection worker.** Add a `reflect(lookback_n=50)` tool that returns a summary of recent lessons grouped by category — the orchestrator reads it and proposes a new `AGENTS.md` draft. Already half-built (`propose_fix` does the pattern-match half).
+3. **Per-check tooling.** Compose with Ruff/mypy/pytest via subprocess and feed results into the same `Finding` shape.
+4. **DSPy offline optimization.** Once you have a labelled "what worked / didn't" set, run GEPA/MIPROv2 against this agent's prompts as a batch job.
+5. **Project isolation.** Multi-tenant the SQLite by `project_root` so a monorepo can keep per-package lessons.
+
+## License
+
+MIT.

smart_agent_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,87 @@
+[project]
+name = "smart-agent-mcp"
+version = "0.1.0"
+description = "A stateful coding-analysis MCP specialist — persistent lesson store, deterministic checks, evolving AGENTS.md."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "cbunt" },
+]
+keywords = [
+    "mcp",
+    "agent",
+    "code-analysis",
+    "self-improving",
+    "memory",
+    "model-context-protocol",
+    "static-analysis",
+    "lint",
+    "reflection",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Standalone FastMCP (Prefect) — actively maintained, v3.x.
+    # NOT the legacy `mcp.server.fastmcp` 1.0 surface in the official SDK.
+    "fastmcp>=3.0,<4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/cbuntingde/smart-agent"
+Repository = "https://github.com/cbuntingde/smart-agent.git"
+Issues = "https://github.com/cbuntingde/smart-agent/issues"
+Changelog = "https://github.com/cbuntingde/smart-agent/releases"
+
+[project.scripts]
+# Entry point. `smart-agent [serve]` runs the MCP server; `smart-agent doctor`
+# runs diagnostics. Default subcommand is `serve`.
+smart-agent = "smart_agent.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+]
+
+# PEP 735 — uv uses this for `uv sync --group dev` etc. Equivalent to the
+# `dev` extra above but recognised by uv tooling.
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+# Hatchling auto-includes LICENSE / README / NOTICE from the project root
+# into the wheel's dist-info. No explicit force-include needed.
+[tool.hatch.build.targets.wheel]
+packages = ["smart_agent"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]

smart_agent_mcp-0.1.0/smart_agent/__init__.py

@@ -0,0 +1,24 @@
+"""smart-agent — a stateful coding-analysis MCP specialist.
+
+Design (see README.md for full evolution model):
+
+  - Tools: record_lesson, recall_lessons, analyze_path, recent_lessons,
+           get_conventions, set_convention, propose_fix.
+  - Resources: memory://recent (live updates), conventions://current.
+  - Storage: SQLite + FTS5 lesson store at ~/.local/share/smart-agent/store.db.
+  - Conventions: AGENTS.md as a human-readable, agent-curated rule file.
+
+The smart agent does NOT call any LLM itself — every "intelligence" call
+comes from the orchestrator (Kimi Code / Claude Code / etc). The agent's
+job is to (a) hold persistent state across sessions, (b) run deterministic
+static checks the LLM can't be trusted with, (c) make past lessons
+trivially retrievable so the orchestrator can apply them.
+
+That's what enables "evolution" today: persistent lessons + an orchestrator
+that follows the recall-at-start / record-at-end convention.
+"""
+
+from smart_agent.config import Config
+
+__all__ = ["Config"]
+__version__ = "0.1.0"