Merge pull request #3 from drknowhow/feat/cross-project-tools

feat(2.31.0): cross-project tools - c3_project MCP tool

Author: drknowhow

CHANGELOG.md

@@ -6,6 +6,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.31.0] - 2026-06-09
+
+Feature release. C3 tools can now reach **outside the current workspace** to
+discover and operate on *other* c3-installed projects. A new `c3_project` MCP
+tool lists/scans for projects that have a `.c3` directory and proxies the core
+C3 operations (search, read, compress, status, memory, impact, edits, validate,
+filter) against any of them — plus guarded writes (`edit`, `shell`, memory
+mutations) behind an explicit `allow_write=true`.
+
+### Added
+
+- `services/project_runtime.py` — shared, thread-safe `ProjectRuntimeCache`
+  (LRU, `.c3`-validated) that builds one `C3Runtime` per foreign project via the
+  existing `build_runtime`; plus `resolve_project()` (name-or-path resolution
+  against the global registry) and `scan_for_c3()` / `discover_projects()`
+  (registry + bounded filesystem scan for unregistered `.c3` projects).
+- `cli/tools/project.py` and the `c3_project` MCP tool — action-dispatch surface:
+  discovery (`list`, `scan`, `info`, `register`, `unregister`), read ops
+  (`search`, `read`, `compress`, `status`, `memory`, `impact`, `edits`,
+  `validate`, `filter`), and guarded write ops (`edit`, `shell`, memory
+  `add/update/delete`). Foreign mutations are logged to the *target* project's
+  activity log and edit ledger.
+- `mcp__c3__c3_project` added to `_C3_MCP_ALLOW` in `cli/c3.py`.
+- `tests/test_project_tool.py` covering the resolver, discovery, runtime-cache
+  LRU/validation, and the dispatcher (read proxy + write guard + audit).
+
+### Changed
+
+- `__version__` in `cli/c3.py` and `version` in `pyproject.toml` bumped to
+  `2.31.0` (kept in sync).
+
+### Why
+
+Until now every C3 capability was scoped to the single project the MCP server
+was launched in. Cross-project work meant switching workspaces. `c3_project`
+lets an agent stay in one session, see which sibling projects have C3 installed,
+and search/read/edit across them — while keeping writes explicit and auditable
+on the project they land in.
+
 ## [2.30.0] - 2026-05-07
 
 Feature release. Adds first-class Bitbucket Data Center / Server (self-hosted

README.md

@@ -166,7 +166,7 @@ Per-project knobs for everything: budget thresholds, feature flag mode, edit led
 
 ## The MCP tool suite
 
-C3 exposes 15 tools as a native MCP server. Your IDE calls them directly:
+C3 exposes 16 tools as a native MCP server. Your IDE calls them directly:
 
 | Tool | What it does |
 |---|---|
@@ -185,8 +185,9 @@ C3 exposes 15 tools as a native MCP server. Your IDE calls them directly:
 | `c3_agent` | Multi-step agentic workflows (review, investigate, refactor) |
 | `c3_edits` | Edit-ledger queries + version diffs + restore points |
 | `c3_bitbucket` | Bitbucket Data Center integration — PRs, branches, builds, repo admin (v2.30.0) |
+| `c3_project` | Cross-project — discover & operate on other c3-installed projects; guarded writes (v2.31.0) |
 
-Every tool is **read-only safe in plan mode** (except `c3_edit`, `c3_shell`, and write actions on `c3_bitbucket`).
+Every tool is **read-only safe in plan mode** (except `c3_edit`, `c3_shell`, and write actions on `c3_bitbucket` / `c3_project`).
 
 ### Bitbucket Data Center / Server (v2.30.0)
 

cli/c3.py

@@ -85,7 +85,7 @@
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.30.0"
+__version__ = "2.31.0"
 
 
 def _command_deps() -> CommandDeps:
@@ -239,6 +239,7 @@ def print_savings(savings: dict):
     "mcp__c3__c3_memory", "mcp__c3__c3_validate", "mcp__c3__c3_edit",
     "mcp__c3__c3_agent", "mcp__c3__c3_delegate", "mcp__c3__c3_edits",
     "mcp__c3__c3_impact", "mcp__c3__c3_shell", "mcp__c3__c3_bitbucket",
+    "mcp__c3__c3_project",
 ]
 
 # Obsolete MCP tool names from earlier C3 versions. `c3 permissions clean`
@@ -4492,6 +4493,7 @@ def _uninstall_mcp_all(project_path: str):
 - **Memory**: `c3_memory(action='recall')` — full recall. `index` + `fetch` for token-efficient two-step retrieval
 - **Delegate**: `c3_delegate(task, backend='ollama|codex|gemini|claude|auto')` — offload to other models
 - **Bitbucket** (v2.30.0+, when `c3 bitbucket login` has run): `c3_bitbucket(action='list_prs|get_pr|merge_pr|...')` — self-hosted Bitbucket Data Center / Server. Token in OS keyring; mutating actions auto-log to the edit ledger.
+- **Cross-project** (v2.31.0+): `c3_project(action='list|scan|search|read|edit|...', project='<name|path>')` — discover and operate on OTHER c3-installed projects. Reads run freely; writes (edit/shell/memory) need `allow_write=true`.
 
 ## Self-Check
 If you haven't called a c3_* tool in several turns during active development, re-engage

cli/docs.html

@@ -1148,7 +1148,7 @@ <h3>Graceful Degradation</h3>
 
       <!-- ─── MCP Tools ───────────────────── -->
       <h2 id="mcp-tools">MCP Tools Reference</h2>
-      <p>C3 exposes 15 MCP tools. All core tools work without Ollama; delegate requires it. The Bitbucket integration is optional and activated via <code>c3 bitbucket login</code>.</p>
+      <p>C3 exposes 16 MCP tools. All core tools work without Ollama; delegate requires it. The Bitbucket integration is optional and activated via <code>c3 bitbucket login</code>.</p>
 
       <h3>Discovery &amp; Compression</h3>
       <table>

cli/mcp_server.py

@@ -699,6 +699,65 @@ def finalize(fname, fargs, fresp, fsumm, **kw):
     )
 
 
+@mcp.tool()
+async def c3_project(
+    action: str,
+    project: str = "",
+    query: str = "",
+    file_path: str = "",
+    symbols: Any = None,
+    lines: Any = None,
+    mode: str = "map",
+    view: str = "health",
+    top_k: int = 5,
+    max_tokens: int = 1200,
+    search_action: str = "code",
+    mem_action: str = "recall",
+    fact: str = "",
+    category: str = "",
+    fact_id: str = "",
+    edits_action: str = "history",
+    file: str = "",
+    tag: str = "",
+    limit: int = 50,
+    target: str = "",
+    old_string: str = "",
+    new_string: str = "",
+    summary: str = "",
+    edits: str = "",
+    replace_all: bool = False,
+    tags: str = "",
+    cmd: str = "",
+    timeout: int = 60,
+    scan_roots: str = "",
+    allow_write: bool = False,
+    ctx: Context = None,
+) -> str:
+    """CROSS-PROJECT — run C3 against OTHER c3-installed projects (read-only safe in plan mode).
+    Discover: list (registry), scan (registry+filesystem), info, register, unregister.
+    Read    : search, read, compress, status, memory, impact, edits, validate, filter.
+    Write   : edit, shell, memory(add/update/delete) — require allow_write=true; logged to that project's ledger.
+    project = registered name OR absolute path (.c3 required). list/scan need no project.
+    search_action/mem_action/edits_action pick the sub-op for those verbs."""
+    svc = _svc(ctx)
+
+    def finalize(fname, fargs, fresp, fsumm, **kw):
+        return _finalize_response(ctx, fname, fargs, fresp, fsumm, **kw)
+
+    from cli.tools.project import handle_project
+    return await asyncio.to_thread(
+        handle_project, action, svc, finalize,
+        project=project, query=query, file_path=file_path, symbols=symbols,
+        lines=lines, mode=mode, view=view, top_k=top_k, max_tokens=max_tokens,
+        search_action=search_action, mem_action=mem_action, fact=fact,
+        category=category, fact_id=fact_id, edits_action=edits_action, file=file,
+        tag=tag, limit=limit, target=target, old_string=old_string,
+        new_string=new_string, summary=summary, edits=edits,
+        replace_all=replace_all, tags=tags, cmd=cmd, timeout=timeout,
+        scan_roots=scan_roots, allow_write=allow_write,
+    )
+
+
 def main() -> None:
     """Entry-point for the ``c3-mcp`` console script."""
     from services import error_reporting