chore(release): v0.3.3 mcp install helper

Author: CharlieGreenman

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `state-trace` are documented here. The format roughly follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/) (with the usual pre-1.0 caveat that minor bumps may include breaking changes).
 
+## [Unreleased]
+
+## [0.3.3] — 2026-04-25
+
+### Added
+
+- `state-trace-mcp-config` helper command, plus `python -m state_trace.mcp_config`, to generate project-scoped `.mcp.json` with an absolute installed `state-trace-mcp` command path. This makes Codex and other MCP clients more reliable when they launch servers with a minimal PATH.
+
+### Changed
+
+- README MCP install docs now separate official PyPI installs from editable source installs and lead with per-repo Codex `.mcp.json` setup.
+- `server.json` package metadata now matches the current `0.3.3` PyPI version.
+
 ## [0.3.2] — 2026-04-25
 
 ### Fixed
@@ -92,6 +105,9 @@ All 52 tests pass. No public API changes.
 - FastAPI surface with `/store`, `/retrieve`, `/retrieve_brief`, `/graph` endpoints.
 - Repo-local benchmark suite: held-out live, offline retrieval, Graphiti head-to-head, budgeted harness proxy, live harness replay, long-horizon memory pressure.
 
+[Unreleased]: https://github.com/razroo/state-trace/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/razroo/state-trace/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/razroo/state-trace/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/razroo/state-trace/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/razroo/state-trace/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/razroo/state-trace/compare/v0.2.0...v0.2.1

README.md

@@ -143,8 +143,11 @@ They solve adjacent problems. The only reason a comparison is even interesting i
 ## Installation
 
 ```bash
-uv sync                       # or: pip install -e .
-pip install -e ".[mcp]"       # stdio MCP server for Claude Code / Cursor / Codex CLI
+pip install "state-trace"      # library
+pip install "state-trace[mcp]" # stdio MCP server for Claude Code / Cursor / Codex CLI
+
+uv sync                       # repo development
+pip install -e ".[mcp]"       # editable MCP install for local development
 pip install -e ".[bench]"     # graphiti-core[kuzu] + datasets (for the headline benchmark)
 pip install -e ".[llm]"       # OpenAI-backed live benchmarks + LLM ingestion
 pip install -e ".[adapters]"  # LangGraph / LlamaIndex adapter shims
@@ -194,11 +197,22 @@ failures = engine.failed_hypotheses(session="auth-debug")
 
 ## MCP Server
 
+Install the official PyPI package:
+
 ```bash
-pip install -e ".[mcp]"
+python3 -m pip install --upgrade "state-trace[mcp]"
 state-trace-mcp
 ```
 
+For project-scoped MCP installs, generate a local `.mcp.json` from the installed package. The generated config uses an absolute `state-trace-mcp` path so clients with a minimal PATH can still start it.
+
+```bash
+cd /path/to/your/repo
+state-trace-mcp-config --namespace "$(basename "$PWD")" > .mcp.json
+# If your shell cannot find the console script:
+python3 -m state_trace.mcp_config --namespace "$(basename "$PWD")" > .mcp.json
+```
+
 Environment config:
 
 - `STATE_TRACE_STORAGE_PATH` — durable path; `.db`/`.sqlite` uses the SQLite backend. Default: `~/.state-trace/memory.db`.
@@ -207,22 +221,79 @@ Environment config:
 
 Tools exposed: `store`, `retrieve`, `retrieve_brief`, `record_action`, `record_observation`, `record_test_result`, `ingest_agent_log_file`, `current_state`, `failed_hypotheses`, `list_namespaces`, `graph_snapshot`.
 
-Example Claude Code config (`~/.claude/settings.json`):
+### OpenAI Codex
+
+Recommended per-repo install:
+
+```bash
+python3 -m pip install --upgrade "state-trace[mcp]"
+cd /path/to/your/repo
+state-trace-mcp-config --namespace "$(basename "$PWD")" > .mcp.json
+# If your shell cannot find the console script:
+python3 -m state_trace.mcp_config --namespace "$(basename "$PWD")" > .mcp.json
+```
+
+Manual project-level `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "state-trace": {
-      "command": "state-trace-mcp",
+      "command": "/absolute/path/to/state-trace-mcp",
       "env": {
-        "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/memory.db",
-        "STATE_TRACE_NAMESPACE": "repo-x"
+        "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/repo-x.db",
+        "STATE_TRACE_NAMESPACE": "repo-x",
+        "STATE_TRACE_CAPACITY_LIMIT": "256"
       }
     }
   }
 }
 ```
 
+Restart Codex after adding or changing `.mcp.json`.
+
+Codex also supports global MCP config:
+
+```bash
+STATE_TRACE_MCP="$(python3 -c 'from state_trace.mcp_config import resolve_entrypoint; print(resolve_entrypoint())')"
+codex mcp add state-trace \
+  --env STATE_TRACE_NAMESPACE=repo-x \
+  --env STATE_TRACE_STORAGE_PATH=/Users/me/.state-trace/repo-x.db \
+  -- "$STATE_TRACE_MCP"
+```
+
+Use the project `.mcp.json` path when you want state-trace mounted one repo at a time.
+
+### Claude Code
+
+Project-level `.mcp.json` is the same as Codex. For a global install:
+
+```bash
+claude mcp add state-trace -- state-trace-mcp
+```
+
+To uninstall:
+
+```bash
+claude mcp remove state-trace
+```
+
+### Cursor
+
+Open Settings → MCP → Add new MCP server, or add the same `mcpServers.state-trace` entry to `.cursor/mcp.json`.
+
+### Other MCP clients
+
+Any MCP client that supports stdio transport can run:
+
+```json
+{
+  "command": "/absolute/path/to/state-trace-mcp"
+}
+```
+
+Use `python3 -m state_trace.mcp_config` to print a complete config with storage, namespace, and capacity env vars.
+
 ## Online agent loop
 
 ```python

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "state-trace"
-version = "0.3.2"
+version = "0.3.3"
 description = "Graph-native working memory for coding agents with causal retrieval and bounded capacity."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -43,6 +43,7 @@ adapters = ["langchain-core>=0.3.0", "llama-index-core>=0.11.0"]
 
 [project.scripts]
 state-trace-mcp = "state_trace.mcp_server:main"
+state-trace-mcp-config = "state_trace.mcp_config:main"
 
 [dependency-groups]
 dev = [

server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/razroo/state-trace",
     "source": "github"
   },
-  "version": "0.3.1",
+  "version": "0.3.3",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "state-trace",
-      "version": "0.3.1",
+      "version": "0.3.3",
       "transport": {
         "type": "stdio"
       },

state_trace/mcp_config.py

@@ -0,0 +1,110 @@
+"""Generate project-scoped MCP client config for state-trace."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sysconfig
+from pathlib import Path
+from typing import Any
+
+
+def _script_names() -> tuple[str, ...]:
+    if os.name == "nt":
+        return ("state-trace-mcp.exe", "state-trace-mcp")
+    return ("state-trace-mcp",)
+
+
+def resolve_entrypoint() -> str:
+    """Return an absolute path to the installed state-trace-mcp script."""
+    scripts_dir = sysconfig.get_path("scripts")
+    if scripts_dir:
+        for name in _script_names():
+            candidate = Path(scripts_dir) / name
+            if candidate.exists():
+                return str(candidate)
+
+    found = shutil.which("state-trace-mcp")
+    if found:
+        return found
+
+    return "state-trace-mcp"
+
+
+def build_mcp_config(
+    *,
+    name: str = "state-trace",
+    namespace: str,
+    storage_path: str,
+    capacity_limit: float = 256.0,
+    command: str | None = None,
+) -> dict[str, Any]:
+    capacity = float(capacity_limit)
+    env: dict[str, str] = {
+        "STATE_TRACE_STORAGE_PATH": storage_path,
+        "STATE_TRACE_NAMESPACE": namespace,
+        "STATE_TRACE_CAPACITY_LIMIT": str(int(capacity) if capacity.is_integer() else capacity),
+    }
+    return {
+        "mcpServers": {
+            name: {
+                "command": command or resolve_entrypoint(),
+                "env": env,
+            }
+        }
+    }
+
+
+def _default_namespace() -> str:
+    name = Path.cwd().name.strip()
+    return name or "state-trace"
+
+
+def _default_storage(namespace: str) -> str:
+    return str(Path.home() / ".state-trace" / f"{namespace}.db")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Print a project-level .mcp.json config for the installed state-trace MCP server."
+    )
+    parser.add_argument("--name", default="state-trace", help="MCP server name in the client config.")
+    parser.add_argument(
+        "--namespace",
+        default=None,
+        help="state-trace namespace. Defaults to the current directory name.",
+    )
+    parser.add_argument(
+        "--storage-path",
+        default=None,
+        help="SQLite/JSON memory path. Defaults to ~/.state-trace/<namespace>.db.",
+    )
+    parser.add_argument(
+        "--capacity-limit",
+        type=float,
+        default=256.0,
+        help="Working-memory budget in capacity units.",
+    )
+    parser.add_argument(
+        "--command",
+        default=None,
+        help="Override the state-trace-mcp command path.",
+    )
+    args = parser.parse_args()
+
+    namespace = args.namespace or _default_namespace()
+    storage_path = args.storage_path or _default_storage(namespace)
+    config = build_mcp_config(
+        name=args.name,
+        namespace=namespace,
+        storage_path=storage_path,
+        capacity_limit=args.capacity_limit,
+        command=args.command,
+    )
+    print(json.dumps(config, indent=2))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

tests/test_mcp_config.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from state_trace.mcp_config import build_mcp_config
+
+
+def test_build_mcp_config_uses_project_namespace_and_absolute_command() -> None:
+    config = build_mcp_config(
+        namespace="repo-x",
+        storage_path="/Users/me/.state-trace/repo-x.db",
+        command="/opt/bin/state-trace-mcp",
+    )
+
+    server = config["mcpServers"]["state-trace"]
+    assert server["command"] == "/opt/bin/state-trace-mcp"
+    assert server["env"] == {
+        "STATE_TRACE_STORAGE_PATH": "/Users/me/.state-trace/repo-x.db",
+        "STATE_TRACE_NAMESPACE": "repo-x",
+        "STATE_TRACE_CAPACITY_LIMIT": "256",
+    }
+
+
+def test_build_mcp_config_keeps_fractional_capacity_limit() -> None:
+    config = build_mcp_config(
+        namespace="repo-x",
+        storage_path="/tmp/repo-x.db",
+        capacity_limit=128.5,
+        command="state-trace-mcp",
+    )
+
+    assert config["mcpServers"]["state-trace"]["env"]["STATE_TRACE_CAPACITY_LIMIT"] == "128.5"