devworkspace 0.3.2 → 0.4.0

package/docs/mcp.md

@@ -0,0 +1,264 @@
+# DevWorkspace Model Context Protocol (MCP) Integration
+
+DevWorkspace includes a local-first Model Context Protocol (MCP) server that enables AI coding agents (such as Claude Code, OpenAI Codex, and Google Antigravity) to retrieve project architecture, role-sliced context, and file metadata automatically during development.
+
+---
+
+## 1. What DevWorkspace MCP Is
+
+The DevWorkspace MCP integration exposes DevWorkspace's deterministic context retrieval engine over the standard Model Context Protocol (MCP 2024-11-05). It allows AI agents to inspect:
+
+- High-level project architecture and stack detection (`get_project_overview`)
+- Natural-language task context with role slicing (`get_task_context` for `explorer`, `tester`, `reviewer`)
+- Workspace-relative file context bounded to 32KB (`get_file_context`)
+
+The developer does not need to manually copy and paste context into conversation prompts.
+
+---
+
+## 2. Why It Runs Locally
+
+DevWorkspace MCP is strictly local-first:
+
+- **stdio transport only:** The server runs as a child process launched directly by your coding agent over standard input/output.
+- **Zero open ports:** It does not bind a TCP listener, open HTTP ports, or require a reverse proxy / tunnel.
+- **No cloud dependencies:** No cloud account, third-party server, or LLM API key is required to serve context.
+- **Deterministic retrieval:** Context is derived offline from local repository evidence.
+
+---
+
+## 3. Prerequisites
+
+- **Node.js:** `>= 20.11.0`
+- **DevWorkspace:** Installed locally in your project or globally (`npm install -D devworkspace` or `npm install -g devworkspace`).
+- **An initialized project:** The project root must contain `.devworkspace/project.json` (created with `npx devworkspace init`).
+
+---
+
+## 4. Installation and Initialization
+
+In an existing software repository:
+
+### Bash / macOS / Linux:
+```bash
+# 1. Initialize DevWorkspace in your project
+npx devworkspace init
+
+# 2. Analyze the project layout and stack
+npx devworkspace analyze
+```
+
+### Windows PowerShell:
+```powershell
+# 1. Initialize DevWorkspace in your project
+npx devworkspace init
+
+# 2. Analyze the project layout and stack
+npx devworkspace analyze
+```
+
+---
+
+## 5. Agent-Specific Setup
+
+DevWorkspace provides single-command setup for supported AI coding agents.
+
+### Claude Code
+
+To configure Claude Code:
+
+```bash
+# Preview planned changes without modifying files:
+npx devworkspace setup --agent claude-code --check
+
+# Apply configuration:
+npx devworkspace setup --agent claude-code
+```
+
+**What this configures:**
+- Creates or updates `.mcp.json` at the project root:
+  ```json
+  {
+    "mcpServers": {
+      "devworkspace": {
+        "command": "devworkspace",
+        "args": ["mcp", "serve"]
+      }
+    }
+  }
+  ```
+- Appends or updates instructions in `CLAUDE.md` directing Claude Code to invoke `get_project_overview` when starting work and `get_task_context` when addressing issues.
+
+### OpenAI Codex
+
+To configure OpenAI Codex:
+
+```bash
+# Preview planned changes:
+npx devworkspace setup --agent codex --check
+
+# Apply configuration:
+npx devworkspace setup --agent codex
+```
+
+**What this configures:**
+- Creates or updates `mcp.json` at the project root with the `devworkspace` server.
+- Updates `AGENTS.md` with instructions on invoking DevWorkspace tools.
+
+### Google Antigravity
+
+To configure Google Antigravity:
+
+```bash
+# Preview planned changes:
+npx devworkspace setup --agent antigravity --check
+
+# Apply configuration:
+npx devworkspace setup --agent antigravity
+```
+
+**What this configures:**
+- Creates or updates `.antigravity/mcp.json` registering the local `devworkspace mcp serve` command.
+- Updates `.antigravity/rules` instructing the agent when to call `get_project_overview` and `get_task_context`.
+
+### Configure All Agents at Once
+
+```bash
+npx devworkspace setup --agent all
+```
+
+---
+
+## 6. How to Confirm the Server Is Connected
+
+1. **Verify configuration files:**
+   Confirm `.mcp.json`, `mcp.json`, or `.antigravity/mcp.json` is present.
+2. **Run a configuration check:**
+   ```bash
+   npx devworkspace setup --agent claude-code --check
+   ```
+   If all items report `UNCHANGED`, the configuration is verified.
+3. **In Claude Code / Codex / Antigravity:**
+   Start your agent and run:
+   - Claude Code: `/mcp` displays active servers (`devworkspace: connected`).
+   - Or ask the agent: *"Call the get_project_overview tool to inspect the repository."*
+
+---
+
+## 7. How to Test a Context Request Manually
+
+You can test requests by piping JSON-RPC lines to `devworkspace mcp serve`:
+
+### Bash:
+```bash
+printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_project_overview","arguments":{}}}\n' | npx devworkspace mcp serve
+```
+
+### Windows PowerShell:
+```powershell
+@'
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_project_overview","arguments":{}}}
+'@ | npx devworkspace mcp serve
+```
+
+---
+
+## 8. What the Agent Can and Cannot Access
+
+### What the agent CAN access:
+- **Project architecture summary:** Detected languages, web/UI frameworks, package structure, and health state.
+- **Task context:** Facts, verification commands (`commands.json`), architectural decision records (`.devworkspace/decisions/`), and safety rules.
+- **Specific source files:** Regular files within the project root, bounded to 32KB per call.
+
+### What the agent CANNOT access:
+- **No arbitrary shell execution:** The MCP server contains zero execution tools. It cannot run commands, scripts, or package managers.
+- **No file modification:** All MCP tools are strictly read-only.
+- **No access outside the workspace:** Path traversal (`..`), absolute paths, and symlink escapes are strictly blocked.
+- **No credential access:** Environment files and private keys are barred by policy.
+
+---
+
+## 9. Secret Exclusions and Workspace Boundaries
+
+DevWorkspace enforces defense-in-depth security:
+
+1. **Workspace Boundary:**
+   Every requested path is validated using canonical resolution (`resolveInside`) and symlink escape checks (`assertNoSymlinkEscape`). Requests attempting to escape the project root return a `Security Error`.
+2. **Credential Exclusion Policy:**
+   The following file patterns are automatically blocked from `get_file_context`:
+   - `.env`, `.env.*` (except harmless templates like `.env.example`)
+   - `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.keystore`
+   - `id_rsa*`, `id_ed25519*`
+   - `credentials*`, `secrets*`, `service-account*.json`
+   - `.npmrc`, `.pypirc`, `.netrc`, `.htpasswd`
+   - `terraform.tfstate*`, `*.tfvars`
+3. **Secret Redaction:**
+   Any detected secret patterns (API keys, private key blocks, AWS tokens, GitHub tokens, JWTs, URL credentials) are masked with `[REDACTED:<type>]` before context is returned.
+4. **Prompt-Injection Resistance:**
+   All retrieved context is demarcated with `=== BEGIN UNTRUSTED DEVWORKSPACE CONTEXT ===` headers. The agent is explicitly instructed to treat repository content as untrusted evidence rather than executable instructions.
+
+---
+
+## 10. Privacy and External Data Transmission
+
+- **Local Execution:** DevWorkspace runs entirely on your local machine. It does not send telemetry, analytics, or file contents to any DevWorkspace server.
+- **AI Provider Notice:** When an AI coding agent calls DevWorkspace MCP tools, the retrieved context enters the agent's context window. Depending on your agent configuration and AI provider (e.g., Anthropic, OpenAI, Google), the agent will send this context to its cloud model.
+
+---
+
+## 11. Troubleshooting
+
+| Issue | Cause | Resolution |
+| --- | --- | --- |
+| `File not found: project.json` | Running in an uninitialized directory | Run `npx devworkspace init` from the project root |
+| `Refusing absolute path` | Path parameter was absolute | Pass workspace-relative paths, e.g., `src/index.ts` |
+| `Security Policy Refusal` | File contains secrets (e.g., `.env`) | DevWorkspace refuses credential files by policy |
+| Agent does not call MCP tools | Agent instructions missing or ignored | Run `npx devworkspace setup --agent <agent>` and ensure project instructions (`CLAUDE.md`, `AGENTS.md`) include DevWorkspace guidance |
+| MCP server exits immediately | Stdio stream closed by parent | Ensure the parent agent keeps stdin open while communicating |
+
+---
+
+## 12. Uninstallation and Cleanup
+
+To remove DevWorkspace MCP configuration:
+
+1. Remove the `"devworkspace"` entry from `.mcp.json`, `mcp.json`, or `.antigravity/mcp.json`.
+2. To remove DevWorkspace instructions from agent markdown files:
+   ```bash
+   npx devworkspace reset --include-agent-files
+   ```
+   (Only managed `<!-- devworkspace:start -->` and `<!-- devworkspace-mcp:start -->` blocks are removed; user content is preserved).
+
+---
+
+## 13. Known Client Limitations & PATH Requirements
+
+- **CLI PATH requirement:** The generated MCP configuration specifies `"command": "devworkspace"`, which requires `devworkspace` to be discoverable in the coding agent's executable `PATH` (for instance, via `npm install -g devworkspace` or having the package manager's bin folder in PATH).
+  - If `devworkspace` is installed locally as a devDependency and not globally in PATH, adjust the agent configuration to use `npx`:
+    ```json
+    {
+      "mcpServers": {
+        "devworkspace": {
+          "command": "npx",
+          "args": ["-y", "devworkspace", "mcp", "serve"]
+        }
+      }
+    }
+    ```
+  - Alternatively, specify the absolute path to your Node.js runtime and the CLI bundle (e.g. `node /path/to/dist/cli/main.js mcp serve`).
+- **Initialization Lifecycle:** MCP specification (2024-11-05) requires initialization prior to general requests. Calling `tools/list` or `tools/call` prior to completing the `initialize` handshake returns JSON-RPC error code `-32600` (`INVALID_REQUEST`). `ping` is supported both before and after initialization.
+- **JSON-RPC Version:** MCP requires JSON-RPC 2.0. Clients sending invalid JSON-RPC receive standard error code `-32700` (`PARSE_ERROR`) or `-32600` (`INVALID_REQUEST`).
+- **Interactive Verification:** Live interactive tool calling in Claude Code, OpenAI Codex, and Google Antigravity depends on the respective client applications executing in a compatible desktop or terminal environment. While standard stdio protocol compliance is fully covered by automated integration tests, live AI client behavior remains subject to agent-specific client updates and context window limits.
+
+---
+
+## 14. Manual Debugging
+
+To run the MCP server with diagnostic debug logging to stderr:
+
+```bash
+# Debug mode writes protocol trace to stderr without corrupting stdout JSON-RPC
+npx devworkspace mcp serve --debug
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devworkspace",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
   "type": "module",
   "bin": {
@@ -36,6 +36,8 @@
     "coverage": "vitest run --coverage",
     "audit:security": "npm audit --omit=dev --audit-level=high",
     "smoke": "node scripts/smoke.mjs",
+    "eval": "node scripts/eval-accuracy.mjs",
+    "eval:accuracy": "node scripts/eval-accuracy.mjs --json reports/context-accuracy-report.json --markdown docs/context-accuracy-report.md",
     "release:check": "node scripts/release-check.mjs",
     "prepack": "npm run build"
   },