refactor: modularize MCP server into dedicated modules

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.9.3
+
+- Added: `load_workspace_manifest` and `refresh_context` MCP tools for
+  workspace-first analysis. Aleph can now bind contexts to refreshable
+  workspace files or generated manifests, which is a better default for large
+  codebases and long-lived projects than loading raw files ad hoc.
+- Added: Workspace bindings now persist through memory-pack save/load, and
+  `get_status` / `list_contexts` expose binding metadata for MCP clients.
+- Added: `ALEPH_ACTION_POLICY` / `--action-policy` with `read-write` and
+  `read-only` modes. Read-only mode keeps repo search and file loading
+  available while blocking writes and subprocess execution.
+- Refactored: Workspace-oriented MCP behavior extracted into
+  `mcp/workspace_contexts.py` and `mcp/workspace_tools.py`, plus
+  `mcp/context_tools.py` for session/context MCP behavior, continuing the
+  modularization of `mcp/local_server.py`.
+- Refactored: Continued the MCP server modularization by extracting
+  `mcp/sub_query_orchestration.py`, `mcp/recipe_runtime.py`,
+  `mcp/node_bridge.py`, and `mcp/repl_injection.py`, reducing
+  `mcp/local_server.py` to orchestration plus thin compatibility wrappers.
+- Docs: README and DEVELOPMENT now lead with the large-codebase workflow and
+  document refreshable workspaces plus the read-only action policy.
+- Tests: Added MCP contract coverage for workspace manifests, refreshable
+  file-backed contexts, action-policy enforcement, bootstrap env handling,
+  sub-query orchestration, recipe runtime extraction, node bridge extraction,
+  and REPL injection extraction.
+
 ## 0.9.2
 
 - Refactored: Centralized Aleph, MCP, and sub-query env parsing through typed

DEVELOPMENT.md

@@ -8,9 +8,9 @@ Architecture and development workflow for Aleph.
 
 Aleph is an MCP server implementing the
 [Recursive Language Model](https://arxiv.org/abs/2512.24601) (RLM) paradigm for
-document analysis. Instead of stuffing context into prompts, Aleph stores
-documents in a sandboxed Python REPL and provides tools for iterative
-exploration.
+large-codebase, project, and document analysis. Instead of stuffing context
+into prompts, Aleph stores working data in a sandboxed Python REPL and
+provides tools for iterative exploration.
 
 ---
 
@@ -24,11 +24,17 @@ aleph/
 ├── cli.py               # CLI entry points (aleph-rlm install/doctor)
 ├── mcp/
 │   ├── local_server.py  # MCP server (main entry point)
-│   ├── tool_registry.py # Tool registration helpers
+│   ├── admin_tools.py   # Runtime configure / remote-server MCP tools
 │   ├── actions.py       # Action tools (read/write/run)
+│   ├── context_tools.py # Context load/list/diff/save/load MCP tools
+│   ├── query_tools.py   # Search / peek / semantic-search MCP tools
 │   ├── recipes.py       # Recipe schema validation
+│   ├── reasoning_tools.py # Status / evidence / finalize MCP tools
+│   ├── workspace_contexts.py # Refreshable file / manifest bindings
+│   ├── workspace_tools.py # Workspace-manifest and refresh MCP tools
 │   ├── session.py       # Session serialization
 │   ├── workspace.py     # Workspace root detection
+│   ├── server_bootstrap.py # CLI/env bootstrap for MCP server runtime
 │   └── server.py        # Compatibility entry point (aliases local_server)
 ├── repl/
 │   ├── sandbox.py       # REPLEnvironment -- sandboxed code execution
@@ -65,8 +71,8 @@ pip install -e ".[dev,mcp]"
 # Run tests
 python3 -m pytest -q
 
-# Run MCP server locally (with action tools enabled)
-aleph --enable-actions --tool-docs concise
+# Run MCP server locally (action tools enabled, but kept read-only)
+aleph --enable-actions --action-policy read-only --tool-docs concise
 ```
 
 ---
@@ -90,12 +96,12 @@ The primary entry point for IDE integration. Exposes tools:
 
 | Category            | Tools                                                             |
 |---------------------|-------------------------------------------------------------------|
-| **Context**         | `load_context`, `peek_context`, `search_context`                  |
+| **Context**         | `load_context`, `load_file`, `load_workspace_manifest`, `refresh_context` |
 | **Compute**         | `exec_python`, `get_variable`                                     |
 | **Recursion**       | `sub_query` (RLM-style recursive calls)                           |
 | **Reasoning**       | `think`, `evaluate_progress`, `summarize_so_far`                  |
 | **Output**          | `finalize`, `get_evidence`, `get_status`                          |
-| **Actions**         | `run_command`, `read_file`, `write_file`, `run_tests`             |
+| **Actions**         | `rg_search`, `read_file`, `run_command`, `write_file`, `run_tests` |
 
 ### Sandbox (`repl/sandbox.py`)
 
@@ -109,7 +115,8 @@ The `REPLEnvironment` provides a sandboxed Python execution environment:
 - **Helper injection:** 100+ functions for document analysis
 
 The sandbox is best-effort, not hardened. For untrusted input, use container
-isolation.
+isolation and keep MCP action tools in `--action-policy read-only` unless you
+explicitly need writes or subprocess execution.
 
 ### Sub-Query System (`sub_query/`)
 
@@ -192,11 +199,14 @@ ruff check aleph tests
 
 ## Adding a New Tool
 
-1. Add the tool function in `mcp/local_server.py` inside `_register_tools()`
-2. Decorate with `@self.server.tool()`
-3. Include comprehensive docstring (shown to AI users)
-4. Update `_Session` if tool needs state tracking
-5. Add tests in `tests/`
+1. Prefer a dedicated module under `aleph/mcp/` (for example
+   `workspace_tools.py`, `reasoning_tools.py`) instead of adding more inline
+   closures to `local_server.py`.
+2. Register the module from `AlephMCPServerLocal._register_tools()`
+3. Decorate with `@self.server.tool()`
+4. Include comprehensive docstring (shown to AI users)
+5. Update `_Session` if the tool needs state tracking
+6. Add tests in `tests/`
 
 Example:
 

README.md

@@ -7,8 +7,8 @@
 Aleph is an [MCP server](https://modelcontextprotocol.io/) and skill for
 **Recursive Language Models** (RLMs). It keeps working state — search indexes,
 code execution, evidence, recursion — in a Python process outside the prompt
-window, so the LLM reasons iteratively over repos, logs, documents, and data
-without burning context on raw content.
+window, so the LLM reasons iteratively over large codebases, long-lived
+projects, logs, documents, and data without burning context on raw content.
 
 ```text
 +-----------------+    tool calls     +-----------------------------+
@@ -25,7 +25,8 @@ Why Aleph:
   `exec_typescript` provide a persistent Node.js runtime over the same `ctx`.
 - **Recurse.** Sub-queries and recipes split complex work across multiple
   reasoning passes.
-- **Persist.** Save sessions and resume long investigations later.
+- **Keep workspaces warm.** Bind contexts back to files or generated workspace
+  manifests, refresh them, and resume long investigations later.
 
 ## Quick Start
 
@@ -47,6 +48,12 @@ a structured RLM workflow. Install
 [`docs/prompts/aleph.md`](docs/prompts/aleph.md) into your client's
 command/skill folder — see [MCP_SETUP.md](MCP_SETUP.md) for exact paths.
 
+If you are using action tools on a real repo, the safest default is:
+
+```bash
+aleph --enable-actions --action-policy read-only
+```
+
 ### Cursor
 
 Use **global** MCP (`aleph-rlm install cursor`) for `--workspace-mode any`, or
@@ -83,10 +90,37 @@ aleph-rlm configure --profile codex   # overwrite existing config
 See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for all env vars, CLI
 flags, and runtime `configure(...)` options.
 
-## First Workflow
+## Large Codebase Workflow
+
+If your main use case is a repo or multi-folder project, start by loading a
+compact workspace manifest instead of throwing raw source files into the model
+window. That gives the model a map of the project, lets it search aggressively,
+and keeps the session refreshable as the repo changes.
+
+```python
+load_workspace_manifest(paths=["src", "tests"], context_id="repo")
+rg_search(pattern="FastAPI|APIRouter|router\\.", paths=["src", "tests"], load_context_id="routes")
+load_file(path="pyproject.toml", context_id="pyproject")
+exec_python(code="""
+files = [line for line in ctx.splitlines() if line.startswith("- ")]
+summary = {
+    "indexed_entries": len(files),
+    "top_python_files": [line for line in files if "| python |" in line][:10],
+}
+""", context_id="repo")
+get_variable(name="summary", context_id="repo")
+refresh_context(context_id="repo")
+```
+
+Use `load_workspace_manifest` as the default front door for large codebases and
+projects. Then pull in specific files with `load_file`, search the repo with
+`rg_search`, and refresh the bound context when the workspace changes. Refreshes
+preserve the session's reasoning state, evidence log, and tracked tasks.
+
+### Single File Workflow
 
-Aleph is best when you load data once, do the heavy work inside Aleph, and only
-pull back compact answers.
+Aleph is also strong when you load one large file once, do the heavy work
+inside Aleph, and only pull back compact answers.
 
 ```python
 load_file(path="/absolute/path/to/large_file.log", context_id="doc")
@@ -160,6 +194,7 @@ variables.
 
 | Scenario | What Aleph Is Good At |
 |---|---|
+| Large codebase / project analysis | Build a workspace map, search quickly, load only the files that matter, and keep the session refreshable |
 | Large log analysis | Load big files, trace patterns, correlate events |
 | Codebase navigation | Search symbols, inspect routes, trace behavior |
 | Data exploration | Analyze JSON, CSV, and mixed text with Python helpers |
@@ -171,7 +206,7 @@ variables.
 
 | Category | Primary tools | What they do |
 |---|---|---|
-| Load context | `load_context`, `load_file`, `list_contexts`, `diff_contexts` | Put data into Aleph memory and inspect what is loaded |
+| Load context | `load_context`, `load_file`, `load_workspace_manifest`, `refresh_context`, `list_contexts`, `diff_contexts` | Put data into Aleph memory, bind it back to workspace assets, and inspect what is loaded |
 | Navigate | `search_context`, `semantic_search`, `peek_context`, `chunk_context`, `rg_search` | Find the relevant slice before asking for an answer |
 | Compute | `exec_python`, `exec_javascript`, `exec_typescript`, `get_variable` | Run Python or JS/TS over the full context and retrieve only the derived result |
 | Reason | `think`, `evaluate_progress`, `get_evidence`, `finalize` | Structure progress and close out with evidence |
@@ -273,6 +308,9 @@ explicitly pull it back:
 - `exec_python` stdout, stderr, and return values are bounded independently.
 - `ALEPH_CONTEXT_POLICY=isolated` adds stricter session export/import rules and
   more defensive defaults.
+- `ALEPH_ACTION_POLICY=read-only` (or `--action-policy read-only`) keeps action
+  tools in read-only mode: search and file loading still work, but writes and
+  subprocess execution are blocked.
 
 The safest pattern is always:
 

aleph/__init__.py

@@ -46,4 +46,4 @@
     "BudgetStatus",
 ]
 
-__version__ = "0.9.2"
+__version__ = "0.9.3"