mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/053-remote-mcp-servers.rispec.md

@@ -0,0 +1,119 @@
+# RISE-053: Remote MCP Servers
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/053-remote-mcp-servers.rispec.md
+
+## Creative Intent
+
+mia-code connects to remote MCP servers over HTTP/SSE, extending the agent's capabilities beyond locally-installed tools. A developer configures a remote GitHub MCP server, a Jira server, or a custom deployment API — and the agent uses their tools as naturally as built-in ones. Remote servers bring organizational tooling, cloud APIs, and shared infrastructure into the agent's reach without requiring local installation.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code's MCP integration supports only locally-spawned servers communicating over stdio
+- Remote APIs require custom tool implementations or shell commands with `curl`
+- No SSE (Server-Sent Events) client for real-time updates from remote services
+- Authentication tokens for remote services are passed ad-hoc through environment variables
+- Each remote service integration requires custom code in mia-code's codebase
+- No connection lifecycle management: no reconnection, no timeout, no health monitoring for remote endpoints
+
+**Desired State:**
+- Remote MCP servers are configured in `mia-code.json` alongside local servers
+- HTTP/SSE transport connects to any MCP-compliant remote server
+- Connection lifecycle is managed: connect on first use, reconnect on disconnect, timeout on inactivity
+- Authentication headers (Bearer tokens, API keys) are configurable with environment variable substitution
+- Remote server tools appear in the tool registry identically to local tools
+- Multiple remote servers coexist with their tools namespaced by server name
+
+## Desired Outcome Definition
+
+A developer adds a remote GitHub MCP server to `mia-code.json`. When the agent first needs to create an issue, mia-code connects to the remote server via SSE, fetches the tool list, and registers `github_create_issue` as an available tool. The agent calls it with parameters; mia-code forwards the request over HTTP. If the connection drops, mia-code reconnects automatically. The developer also adds a Jira server — both run simultaneously with no conflicts.
+
+## Natural Language Functional Description
+
+### Configuration
+
+Remote MCP servers are declared in `mia-code.json`:
+
+```json
+{
+  "mcp": {
+    "github": {
+      "type": "remote",
+      "url": "https://mcp.github.example.com/sse",
+      "headers": {
+        "Authorization": "Bearer ${GITHUB_TOKEN}"
+      },
+      "timeout": 30000,
+      "reconnect": true
+    },
+    "jira": {
+      "type": "remote",
+      "url": "https://jira-mcp.internal.company.com/sse",
+      "headers": {
+        "X-API-Key": "${JIRA_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Environment variable substitution:** Values wrapped in `${VAR_NAME}` are resolved from environment variables at connection time. Missing variables produce a clear error before attempting connection.
+
+### Connection Lifecycle
+
+**Connect on first use:** When an agent attempts to use a tool that belongs to a remote server (or when the tool list is first needed), mia-code initiates the SSE connection. No connections are opened at session start — only when needed.
+
+**SSE Connection:** The client opens an SSE stream to the configured URL. The server sends events:
+- `endpoint` — provides the HTTP POST endpoint for sending requests
+- `message` — JSON-RPC responses and notifications from the server
+
+**Tool discovery:** On connection, mia-code sends a `tools/list` request. The server responds with available tools, their schemas, and descriptions. These are registered in the tool registry with the server name prefix.
+
+**Reconnection:** If the SSE connection drops, mia-code attempts reconnection with exponential backoff: 1s, 2s, 4s, 8s, up to 60s maximum. During reconnection, tool calls to this server queue and execute once reconnected. After 10 failed reconnection attempts, the server is marked as unavailable.
+
+**Timeout:** If no communication occurs for the configured timeout period (default 30s for tool calls), the request is aborted with an error. The SSE connection itself has no idle timeout — it remains open as long as the session is active.
+
+**Graceful disconnect:** On session end, mia-code closes all SSE connections cleanly.
+
+### Tool Namespacing
+
+Each remote server's tools are prefixed with the server name to avoid conflicts:
+
+| Server Config Key | MCP Tool Name | Registered As |
+|-------------------|---------------|---------------|
+| `github` | `create_issue` | `github_create_issue` |
+| `github` | `search_code` | `github_search_code` |
+| `jira` | `create_issue` | `jira_create_issue` |
+
+The prefix is configurable per server: `"prefix": "gh"` would produce `gh_create_issue`. Setting `"prefix": ""` disables prefixing (use with caution for conflicts).
+
+### Tool List Refresh
+
+When the remote server sends a `notifications/tools/list_changed` notification, mia-code re-fetches the tool list. Tools that no longer exist are deregistered. New tools are registered. This allows remote servers to dynamically add or remove capabilities.
+
+### Request Forwarding and Server Isolation
+
+When an agent calls a remote tool, mia-code constructs a `tools/call` JSON-RPC request (using the original unprefixed name), POSTs it to the SSE-provided endpoint, and correlates the response by request ID. Each remote server has its own SSE connection, auth headers, tool namespace, and reconnection state — servers cannot interfere with each other.
+
+## Supporting Structures
+
+- **MCP Tool Conversion (RISE-055)** wraps remote tools as native mia-code tools
+- **MCP Connection Monitoring (RISE-056)** tracks health of remote connections
+- **MCP OAuth Flow (RISE-054)** handles OAuth authentication for servers that require it
+- **Event Bus (RISE-002)** publishes `mcp.connected`, `mcp.disconnected` events for remote servers
+- **Structured Logging (RISE-007)** logs connection lifecycle events and request/response pairs
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — GitHub Integration:**
+A developer configures a remote GitHub MCP server. The agent can now create issues, search code, open PRs, and review diffs using `github_create_issue`, `github_search_code`, etc. All tool calls route through the remote server — no GitHub CLI installation needed locally.
+
+**Scenario 2 — Multi-Server Workflow:**
+An agent working on a bug report reads the issue from Jira (`jira_get_issue`), searches the codebase for the relevant code (`github_search_code`), writes a fix, then creates a PR (`github_create_pr`) and updates the Jira ticket (`jira_update_issue`). Three remote servers participate seamlessly in one workflow.
+
+**Scenario 3 — Reconnection Under Flaky Network:**
+During a long coding session, the developer's VPN reconnects. The GitHub SSE connection drops. mia-code detects the disconnect, waits 1 second, reconnects successfully, and re-fetches the tool list. The agent's next `github_create_issue` call works without the agent knowing anything happened.
+
+**Scenario 4 — Dynamic Tool Updates:**
+A remote MCP server is updated to add new tools. It sends a `list_changed` notification. mia-code re-fetches the tool list and discovers `deploy_preview` — a new tool. The agent can immediately use it in the current session without restart.

package/rispecs/borrowed_from_opencode/054-mcp-oauth-flow.rispec.md

@@ -0,0 +1,107 @@
+# RISE-054: MCP OAuth Flow
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/054-mcp-oauth-flow.rispec.md
+
+## Creative Intent
+
+mia-code handles OAuth 2.0 authentication for MCP servers that require it, so developers authorize once and agents use secured APIs seamlessly. The developer sees a browser prompt, clicks "Authorize," and mia-code stores tokens securely for all future sessions. No manual token management, no copying secrets into config files — the authentication flow is as smooth as logging into a web app.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- MCP server authentication requires manually generating tokens and pasting them into configuration files
+- Bearer tokens in `mia-code.json` are static — they expire and require manual rotation
+- No mechanism for the OAuth authorization code flow (browser redirect, callback handling)
+- Token refresh is manual: when a token expires, the agent fails and the developer must regenerate
+- Credential storage is ad-hoc: tokens in config files, environment variables, or `.env` files with varying security
+- Dynamic client registration (RFC 7591) is not supported — developers must manually register OAuth apps
+
+**Desired State:**
+- MCP servers declare OAuth requirements in their configuration
+- mia-code runs the full OAuth 2.0 authorization code flow with PKCE
+- A local HTTP server handles the callback redirect
+- Tokens are stored securely in `~/.mia-code/auth/` with appropriate file permissions
+- Access tokens are refreshed automatically using refresh tokens before expiration
+- Dynamic client registration creates client credentials automatically when supported
+- Multiple OAuth-authenticated servers can run simultaneously
+
+## Desired Outcome Definition
+
+A developer adds a remote MCP server that requires OAuth. On first connection, mia-code opens the browser to the authorization URL. The developer logs in and clicks "Authorize." The browser redirects to `localhost:9876/callback`. mia-code exchanges the code for tokens, stores them in `~/.mia-code/auth/mcp-github.json`, and connects to the server. On subsequent sessions, stored tokens are used automatically — refreshed if expired.
+
+## Natural Language Functional Description
+
+### OAuth Configuration
+
+MCP servers declare OAuth requirements in `mia-code.json`:
+
+```json
+{
+  "mcp": {
+    "github": {
+      "type": "remote",
+      "url": "https://mcp.github.example.com/sse",
+      "auth": {
+        "type": "oauth",
+        "authorizationUrl": "https://github.com/login/oauth/authorize",
+        "tokenUrl": "https://github.com/login/oauth/access_token",
+        "clientId": "abc123",
+        "scopes": ["repo", "read:org"],
+        "callbackPort": 9876
+      }
+    }
+  }
+}
+```
+
+Alternatively, the server may advertise its OAuth metadata via a well-known endpoint (RFC 8414), and mia-code discovers endpoints automatically.
+
+### Authorization Flow
+
+When the MCP server requires auth and no valid token exists, mia-code: (1) generates a PKCE code verifier/challenge and state parameter, (2) constructs the authorization URL with `client_id`, `redirect_uri`, `response_type=code`, `scope`, `state`, `code_challenge`, (3) opens the browser (or displays URL for headless/SSH sessions), (4) starts a temporary callback server on `localhost:PORT` (default 9876), (5) validates the state parameter and exchanges the code for tokens, (6) stores tokens in `~/.mia-code/auth/mcp-{serverId}.json` with 0600 permissions containing `accessToken`, `refreshToken`, `expiresAt`, `scopes`.
+
+### Token Refresh
+
+When an access token is within 5 minutes of expiration (or has already expired):
+1. POST to the token endpoint with: `grant_type=refresh_token`, `refresh_token`, `client_id`
+2. Receive new `access_token` and optionally new `refresh_token`
+3. Update the stored credential file
+4. Retry the failed request with the new token
+
+If refresh fails (refresh token revoked or expired), initiate a new authorization flow.
+
+### Dynamic Client Registration
+
+If the MCP server's OAuth metadata includes a `registration_endpoint` (RFC 7591):
+1. POST client metadata: `redirect_uris`, `client_name` ("mia-code"), `grant_types`, `response_types`, `token_endpoint_auth_method`
+2. Receive `client_id` and optionally `client_secret`
+3. Store registration in `~/.mia-code/auth/mcp-{serverId}-client.json`
+4. Use these credentials for subsequent authorization flows
+
+This eliminates the need for developers to manually register OAuth applications.
+
+### Security and Multi-Server Support
+
+All flows require PKCE (RFC 7636) and state parameters for CSRF protection. Token files have restrictive 0600 permissions. Tokens are never logged. The callback server runs only during authorization (seconds). If the callback port is in use, the next 5 ports are tried. Each OAuth server has independent token storage — re-authorizing one does not affect others.
+
+## Supporting Structures
+
+- **Remote MCP Servers (RISE-053)** initiates OAuth when connecting to servers that require it
+- **MCP Connection Monitoring (RISE-056)** reports auth failures as connection errors
+- **Structured Logging (RISE-007)** logs OAuth flow steps (without tokens) for debugging
+- **Event Bus (RISE-002)** publishes `mcp.auth.started`, `mcp.auth.completed`, `mcp.auth.failed` events
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — First-Time Authorization:**
+A developer adds a GitHub MCP server with OAuth config. On first `github_create_issue` call, mia-code opens the browser to GitHub's authorization page. The developer logs in, authorizes the app, and the browser shows "Authorization successful — you may close this tab." mia-code stores the tokens and the tool call completes.
+
+**Scenario 2 — Silent Token Refresh:**
+Three hours into a session, the GitHub access token expires. The agent calls `github_search_code`. mia-code detects the expired token, uses the refresh token to get a new access token, retries the request, and returns results. The agent never knows auth happened.
+
+**Scenario 3 — Headless Environment:**
+A developer runs mia-code over SSH with no browser. When OAuth is needed, mia-code prints: "Open this URL to authorize: https://github.com/login/oauth/authorize?..." and waits. The developer opens the URL on their phone, authorizes, and the callback is received on the SSH host's localhost. Tokens are stored and the session continues.
+
+**Scenario 4 — Dynamic Registration:**
+A company deploys a custom MCP server with dynamic client registration. A new developer runs mia-code for the first time. mia-code auto-registers a client, initiates OAuth, and the developer authorizes. No admin needed to create OAuth app credentials — it's all automatic.

package/rispecs/borrowed_from_opencode/055-mcp-tool-conversion.rispec.md

@@ -0,0 +1,118 @@
+# RISE-055: MCP Tool Conversion
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/055-mcp-tool-conversion.rispec.md
+
+## Creative Intent
+
+mia-code converts MCP server tools into native tools so agents use them identically to built-in capabilities. A tool from a remote GitHub server and a tool from a local file-system server go through the same permission checks, receive the same context injection, and produce the same output format. The agent doesn't know or care whether a tool is built-in, from a local MCP server, or from a remote one — it just works.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- MCP tools exist in a separate namespace from native mia-code tools
+- Agents must use different invocation patterns for MCP tools vs. built-in tools
+- MCP tool schemas are JSON Schema; mia-code internal tools use Zod schemas — no conversion bridge
+- Permission checks (RISE-011) apply only to built-in tools; MCP tools bypass the permission system
+- MCP tool output format varies by server; agents must handle different response structures
+- No duplicate detection: an MCP server could register a tool named `read_file` that conflicts with the built-in
+
+**Desired State:**
+- Every MCP tool is automatically wrapped as a native mia-code tool on registration
+- JSON Schema parameters are converted to Zod schemas for validation
+- Converted tools pass through the same permission system as built-in tools
+- Tool output is normalized to a consistent format regardless of source
+- Naming conflicts are detected and reported with configurable resolution
+- Tool availability updates dynamically when MCP servers send `list_changed` notifications
+
+## Desired Outcome Definition
+
+A remote MCP server connects and provides 5 tools. mia-code wraps each one: JSON Schema → Zod schema, MCP description → tool description, MCP execute → wrapped call. The 5 tools appear in the agent's tool list alongside built-in tools. The agent calls `github_create_issue({title: "Bug", body: "Details"})` — mia-code validates parameters with the Zod schema, checks permissions, forwards to the MCP server, normalizes the response, and returns it to the agent.
+
+## Natural Language Functional Description
+
+### Conversion Pipeline
+
+When an MCP server provides its tool list (via `tools/list` response), each tool goes through a conversion pipeline:
+
+**Step 1 — Schema Conversion:**
+The MCP tool's `inputSchema` (JSON Schema) is converted to a Zod schema:
+- `type: "string"` → `z.string()`
+- `type: "number"` → `z.number()`
+- `type: "boolean"` → `z.boolean()`
+- `type: "object"` with `properties` → `z.object({...})` with nested conversion
+- `type: "array"` with `items` → `z.array(z.string())` etc.
+- `required` fields → non-optional; others → `.optional()`
+- `enum` values → `z.enum([...])`
+- `description` → `.describe("...")`
+
+Complex schemas (oneOf, anyOf, allOf, $ref) are handled via recursive conversion. Unsupported constructs fall back to `z.any()` with a warning.
+
+**Step 2 — Name Registration:**
+The tool name is prefixed with the server name: `create_issue` → `github_create_issue`. The prefix is configurable (RISE-053). The converted name is checked against the existing tool registry:
+- If no conflict: register normally
+- If conflicts with a built-in tool: log a warning, keep the MCP tool with its prefix
+- If conflicts with another MCP tool: log an error, the later tool is registered with a numeric suffix (`github_create_issue_2`)
+
+**Step 3 — Description Mapping:**
+The MCP tool's `description` becomes the native tool's description. If the MCP tool has no description, a default is generated: `"Tool '{name}' from MCP server '{serverId}'"`.
+
+**Step 4 — Execute Wrapper:**
+A wrapper function is created that:
+1. Receives validated parameters (already checked by Zod schema)
+2. Constructs a `tools/call` MCP request with the original tool name and parameters
+3. Sends the request via the MCP client (local stdio or remote HTTP)
+4. Receives the MCP result
+5. Normalizes the output format
+6. Returns the result in standard tool output format
+
+### Output Normalization
+
+MCP tool results follow the MCP content format (`content: [{type: "text", text: "..."}]`). The normalizer converts to mia-code's standard output:
+
+- **Text content:** extracted and joined with newlines
+- **Image content:** converted to markdown image references or base64 data URIs
+- **Resource content:** embedded with metadata (URI, MIME type)
+- **Error results:** mapped to tool error format with `isError: true`
+
+```
+MCP Response:
+{content: [{type: "text", text: "Issue #42 created"}, {type: "text", text: "URL: https://..."}]}
+
+Normalized Output:
+"Issue #42 created\nURL: https://..."
+```
+
+### Permission Integration
+
+Converted MCP tools are subject to the same permission system as built-in tools (RISE-011):
+- The agent's permission ruleset includes MCP tool permissions
+- Default: MCP tools require explicit approval on first use per session
+- Configurable auto-approve per server: `"autoApprove": ["create_issue", "search_code"]`
+- Dangerous operations (delete, deploy) default to require approval regardless of config
+
+### Dynamic Updates and Introspection
+
+When an MCP server sends `notifications/tools/list_changed`, mia-code re-fetches the tool list, registers new tools, deregisters removed ones, and updates changed schemas. Agents can query tool metadata to see provenance: `{name: "github_create_issue", source: "mcp", serverId: "github", originalName: "create_issue"}`.
+
+## Supporting Structures
+
+- **Remote MCP Servers (RISE-053)** provides the remote tools to convert
+- **Local MCP Servers (RISE-057)** provides locally-spawned server tools to convert
+- **Zod Schema Validation (RISE-005)** provides the schema system tools are converted into
+- **Agent Permission Rulesets (RISE-011)** governs approval for converted MCP tools
+- **Event Bus (RISE-002)** publishes `tools.registered`, `tools.deregistered`, `tools.updated` events
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Seamless Integration:**
+A developer configures a local database MCP server and a remote GitHub MCP server. The agent sees `db_query`, `db_insert`, `github_create_issue`, `github_search_code` alongside built-in tools like `read_file` and `write_file`. It uses them interchangeably in the same workflow: read a file, query the database, create a GitHub issue — all with identical invocation patterns.
+
+**Scenario 2 — Schema Validation Catches Errors:**
+An agent tries to call `github_create_issue` with `{title: 42}` (number instead of string). The Zod schema validation catches the error before the request reaches the MCP server: `"Expected string, received number at 'title'"`. The agent corrects the parameter type.
+
+**Scenario 3 — Conflict Detection:**
+A developer adds two MCP servers that both provide a `search` tool. mia-code detects the conflict and registers them as `server1_search` and `server2_search`. A warning is logged: `"Tool name conflict: 'search' provided by both 'server1' and 'server2'"`. The agent can use both tools without ambiguity.
+
+**Scenario 4 — Live Tool Updates:**
+A custom MCP server is redeployed with a new `deploy_preview` tool added. The server sends `list_changed`. mia-code re-fetches, converts the new tool, and registers it. The agent discovers it in its next tool list query and starts using it — all within the same session, no restart needed.

package/rispecs/borrowed_from_opencode/056-mcp-connection-monitoring.rispec.md

@@ -0,0 +1,106 @@
+# RISE-056: MCP Connection Monitoring
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/056-mcp-connection-monitoring.rispec.md
+
+## Creative Intent
+
+mia-code monitors the health of every MCP server connection, giving agents and developers clear visibility into what's working, what's broken, and what's recovering. A dashboard shows status at a glance — green for connected, red for failed, yellow for reconnecting. Auto-reconnect with exponential backoff keeps transient failures invisible to the agent. When something is truly down, the error details are immediate and actionable.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- MCP server connections have no health tracking — a crashed server is discovered only when a tool call fails
+- No reconnection logic: if a server disconnects, it stays disconnected until the session is restarted
+- Error details are lost: server crashes produce generic "tool failed" messages without context
+- No visibility into connection state — the developer cannot see which servers are up or down
+- Stale connections sit open indefinitely, consuming resources even when unused
+- Multiple simultaneous server failures create cascading confusing error messages
+
+**Desired State:**
+- Every MCP server connection has a tracked status: connected, disconnected, connecting, error
+- Auto-reconnect with exponential backoff handles transient failures transparently
+- A `/mcp` slash command shows a live dashboard of all server states
+- Health events are published to the event bus for programmatic consumption
+- Stale connections are detected via periodic pings
+- Error details include last error message, retry count, and next retry time
+
+## Desired Outcome Definition
+
+A developer types `/mcp` and sees a table: GitHub (🟢 connected, 12 tools, last active 30s ago), Jira (🔴 disconnected, retrying in 8s, "connection refused"), Local DB (🟢 connected, 5 tools, last active 2m ago). The GitHub server briefly disconnects — within 1 second it reconnects automatically, the agent never notices. The Jira server is down for maintenance — after 10 retries, it's marked as unavailable, and the agent gets a clear error if it tries to use a Jira tool.
+
+## Natural Language Functional Description
+
+### Connection State Model
+
+Each MCP server connection tracks: `serverId`, `status` (connected/disconnected/connecting/error), `lastSuccessfulCommunication`, `lastError`, `errorCount`, `consecutiveFailures`, `toolCount`, `connectTime`, `nextRetryTime`, `retryAttempt`. Transitions: disconnected → connecting → connected (success) or error (failure); connected → disconnected (on drop); error → connecting (on retry) or disconnected (max retries).
+
+### Auto-Reconnect
+
+On disconnect: exponential backoff at `min(2^attempt * 1000, 60000)ms` — 1s, 2s, 4s, 8s, up to 60s max. On success: reset counters, re-fetch tools. After 10 consecutive failures: stop retrying, mark disconnected.
+
+### Stale Connection Detection
+
+Every 5 minutes (configurable), check `lastSuccessfulCommunication` for each server. If stale: check process liveness (local) or send ping (remote). No response within 10s triggers reconnection.
+
+### Health Events
+
+All state transitions are published to the event bus (RISE-002):
+
+- `mcp.connecting` — `{serverId, attempt, maxAttempts}`
+- `mcp.connected` — `{serverId, toolCount, connectTime}`
+- `mcp.disconnected` — `{serverId, reason, wasClean}`
+- `mcp.error` — `{serverId, error, retryIn, attempt}`
+- `mcp.health.stale` — `{serverId, lastCommunication}`
+- `mcp.health.recovered` — `{serverId, downtime}`
+
+Agents can listen for these events to adapt behavior (e.g., fall back to alternative tools when a server is down).
+
+### Dashboard — `/mcp` Slash Command
+
+The `/mcp` command renders a status table:
+
+```
+MCP Server Status
+─────────────────────────────────────────────────────────
+  Server       Status  Tools  Last Active    Details
+─────────────────────────────────────────────────────────
+  github       🟢       12    30s ago
+  jira         🔴        0    —              connection refused (retry 5/10 in 8s)
+  local-db     🟢        5    2m ago
+  custom-api   🟡        —    —              connecting (attempt 2)
+─────────────────────────────────────────────────────────
+  3 servers configured | 2 connected | 17 tools available
+```
+
+Status emojis:
+- 🟢 Connected and healthy
+- 🟡 Connecting or reconnecting
+- 🔴 Disconnected or error
+- ⚪ Not yet started (lazy initialization)
+
+### Error Reporting and Metrics
+
+When an agent calls a tool from a disconnected server, it receives actionable details: server name, last error, retry state, and URL. Session metrics track per-server uptime, downtime, reconnection count, average reconnection time, and tool call success rates — available via `mcp.metrics` and included in session summaries.
+
+## Supporting Structures
+
+- **Remote MCP Servers (RISE-053)** provides the remote connections to monitor
+- **Local MCP Servers (RISE-057)** provides the local server processes to monitor
+- **Event Bus (RISE-002)** distributes health events to interested subscribers
+- **Structured Logging (RISE-007)** records all health state transitions
+- **Session Persistence (RISE-018)** includes MCP health state in session snapshots
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Transparent Recovery:**
+A remote GitHub server experiences a brief network glitch. The SSE connection drops. mia-code detects the disconnect, publishes `mcp.disconnected`, waits 1 second, reconnects successfully, publishes `mcp.connected`. The agent's next tool call works normally. The developer sees nothing — the recovery was invisible.
+
+**Scenario 2 — Informed Failure:**
+The Jira server is down for maintenance. After 10 reconnection attempts over ~2 minutes of exponential backoff, mia-code marks it as disconnected and stops retrying. The agent tries `jira_create_issue` and receives a clear error: "MCP server 'jira' is disconnected after 10 retry attempts. Last error: connection refused." The agent reports to the developer instead of silently failing.
+
+**Scenario 3 — Developer Debugging:**
+A developer notices tool calls are slow. They type `/mcp` and see the custom API server has reconnected 15 times in the last hour with average reconnection time of 4 seconds. The health metrics reveal the server is unstable. The developer contacts the server maintainer with specific data.
+
+**Scenario 4 — Multi-Server Resilience:**
+Three remote servers are configured. One goes down. The agent detects via health events that `jira` is disconnected and automatically falls back to creating a TODO comment in the code instead of a Jira ticket. When Jira recovers, the agent can retroactively create the tickets from the TODOs.

package/rispecs/borrowed_from_opencode/057-local-mcp-servers.rispec.md

@@ -0,0 +1,116 @@
+# RISE-057: Local MCP Servers
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/057-local-mcp-servers.rispec.md
+
+## Creative Intent
+
+mia-code spawns and manages locally-running MCP servers that communicate over stdio, giving developers a simple way to extend the agent with custom tools. A developer writes an MCP server as a Node.js script, adds it to configuration, and the agent gains new capabilities — database queries, deployment commands, proprietary API wrappers. The server runs as a child process: mia-code handles spawning, health monitoring, restart on crash, and clean shutdown, so developers focus on tool logic, not infrastructure.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code can define MCP server configurations in its three-world model but lacks robust local server lifecycle management
+- No standardized process spawning with health monitoring and automatic restart
+- Environment variable substitution in server configs is limited
+- Process cleanup on session end is not guaranteed — orphaned processes can persist
+- Stderr from child processes is discarded, making debugging server issues difficult
+- No initialization timeout — a broken server can hang the agent indefinitely on startup
+
+**Desired State:**
+- Local MCP servers are configured declaratively in `mia-code.json` with command, args, env, and working directory
+- Servers spawn lazily on first tool use, not at session start
+- Communication uses JSON-RPC 2.0 over stdin/stdout (the MCP stdio transport)
+- Health monitoring detects crashes and restarts servers automatically
+- Environment variables support `${VAR}` substitution from the host environment
+- Stderr is captured and routed to structured logging for debugging
+- Graceful shutdown ensures no orphaned processes when the session ends
+- Initialization timeout prevents hung servers from blocking the agent
+
+## Desired Outcome Definition
+
+A developer adds a local database MCP server to `mia-code.json`. The agent calls `db_query({sql: "SELECT * FROM users"})`. mia-code spawns `node db-mcp-server.js`, initializes the MCP protocol, discovers `query` and `insert` tools, wraps them as `db_query` and `db_insert`, and forwards the call. The server responds with query results. If the server crashes, mia-code restarts it. When the session ends, the server process is terminated cleanly.
+
+## Natural Language Functional Description
+
+### Configuration
+
+Local MCP servers are declared in `mia-code.json`:
+
+```json
+{
+  "mcp": {
+    "local-db": {
+      "type": "local",
+      "command": ["node", "tools/db-mcp-server.js"],
+      "args": ["--connection-string", "${DATABASE_URL}"],
+      "env": {
+        "DB_PASSWORD": "${DB_PASSWORD}",
+        "NODE_ENV": "production"
+      },
+      "cwd": "./tools",
+      "initTimeout": 15000,
+      "restartOnCrash": true,
+      "maxRestarts": 5
+    },
+    "code-analyzer": {
+      "type": "local",
+      "command": ["python", "-m", "analyzer_mcp"],
+      "env": {
+        "PYTHONPATH": "${PROJECT_ROOT}/lib"
+      }
+    }
+  }
+}
+```
+
+**Configuration fields:**
+- `command`: executable and base arguments (required)
+- `args`: additional arguments appended to command (optional)
+- `env`: environment variables for the spawned process (optional)
+- `cwd`: working directory, relative to project root (default: project root)
+- `initTimeout`: milliseconds to wait for server initialization (default: 10000)
+- `restartOnCrash`: whether to auto-restart on unexpected exit (default: true)
+- `maxRestarts`: maximum restart attempts before giving up (default: 5)
+
+### Environment Variable Substitution
+
+Values containing `${VAR_NAME}` are resolved from the host environment at spawn time. Missing variables log a warning. Special variable `${PROJECT_ROOT}` resolves to the session's project root.
+
+### Process Spawning
+
+On first tool use: resolve command with env substitution, spawn via `child_process.spawn()` with piped stdin/stdout/stderr and configured cwd/env, start init timeout, send MCP `initialize`, wait for `initialized` notification, fetch tools via `tools/list`, register via conversion pipeline (RISE-055). If init doesn't complete within `initTimeout`, kill and report error.
+
+### Communication Protocol
+
+All communication uses JSON-RPC 2.0 over stdin/stdout with newline-delimited messages. Each outgoing request has a unique numeric ID for response correlation. A configurable request timeout (default 30s) prevents hung calls.
+
+### Health Monitoring and Crash Recovery
+
+mia-code listens for the `exit` event on each child process. On unexpected exit (code ≠ 0 or signal), it logs the exit details and stderr output, then restarts with exponential backoff (1s, 2s, 4s, max 30s) up to `maxRestarts` attempts. Stderr is captured line-by-line and routed to structured logging at debug level for server-side debugging.
+
+### Graceful Shutdown and Process Isolation
+
+On session end, each server receives a `shutdown` request, then `exit` notification, with escalation to SIGTERM and SIGKILL if needed. Each server runs in its own process with independent streams, environment, and working directory — a crash in one server has no effect on others.
+
+## Supporting Structures
+
+- **MCP Tool Conversion (RISE-055)** wraps discovered tools as native mia-code tools
+- **MCP Connection Monitoring (RISE-056)** tracks the health state of local server processes
+- **Event Bus (RISE-002)** publishes `mcp.local.spawned`, `mcp.local.crashed`, `mcp.local.shutdown` events
+- **Structured Logging (RISE-007)** captures stderr output and lifecycle events
+- **Lazy Initialization (RISE-008)** provides the deferred-start pattern for local servers
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Custom Database Tool:**
+A developer writes a 50-line Node.js MCP server that wraps their PostgreSQL database with `query` and `schema` tools. They add it to `mia-code.json`. The agent can now query the database, inspect table schemas, and write migration SQL — all through standard tool calls. The server persists a connection pool across calls for efficiency.
+
+**Scenario 2 — Crash Recovery:**
+A Python MCP server hits an unhandled exception and crashes. mia-code detects the exit (code 1), logs the traceback from stderr, waits 1 second, respawns the process, reinitializes, and re-registers tools. The agent's next tool call works seamlessly. The developer later reads the debug log to fix the server bug.
+
+**Scenario 3 — Multi-Server Workspace:**
+A project has three local MCP servers: a database tool, a deployment tool, and a documentation indexer. All three spawn lazily — the database tool on first `db_query`, the deployment tool when the agent needs to deploy, and the indexer when asked about documentation. Each runs in isolation. If the deployment tool crashes, queries and docs continue working.
+
+**Scenario 4 — Sensitive Credentials:**
+A local MCP server needs a database password. The developer sets `DB_PASSWORD` in their shell environment and references `${DB_PASSWORD}` in the server's env config. The password never appears in `mia-code.json` or in logs. The spawned process receives it via its environment. If the variable is missing, mia-code warns before spawning rather than passing an empty string to the database.