Release MCP Runtime v0.10.0

AGENTS.md

@@ -0,0 +1,15 @@
+# Agent instructions
+
+## Agent skills
+
+### Issue tracker
+
+Issues and build specifications are tracked in GitHub Issues for `celados/mcpx`. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Use the canonical triage labels defined in `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+This is a single-context repository. Read `CONTEXT.md` and relevant ADRs under `docs/adr/`. See `docs/agents/domain.md`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTEXT.md

@@ -0,0 +1,55 @@
+---
+type: Context
+title: MCPX Domain Language
+description: Canonical vocabulary for the user-local MCP runtime and its command interface.
+---
+
+# MCPX
+
+MCPX gives local commands one consistent authority for discovering, authenticating, and invoking registered MCP servers.
+
+## Language
+
+**MCP Runtime**:
+The single user-local authority for credential lifecycle, active MCP sessions, and tool-call coordination.
+_Avoid_: Daemon, session manager, connection pool when referring to the whole authority
+
+**CLI Adapter**:
+A short-lived command interface that submits intent to the MCP Runtime and renders its response.
+_Avoid_: Client control plane, auth owner
+
+**Declared Registry**:
+The persistent set of MCP server declarations chosen by the user, excluding credentials and observed runtime state.
+_Avoid_: Runtime registry, session config, schema cache
+
+**Credential Store**:
+The durable, sensitive authorization material that lets MCPX act for the user without embedding secrets in server declarations.
+_Avoid_: Auth config, token registry
+
+**Credential Identity**:
+The stable authorization identity shared by every server declaration and call that must use the same grant.
+_Avoid_: Server key, access token, session ID
+
+**Authentication Flow**:
+One explicitly requested, shared attempt to make a Credential Identity usable; ordinary Calls report that authentication is required instead of starting the flow.
+_Avoid_: Per-command login, token retry
+
+**Caller Input**:
+A request/response on the active Runtime connection for secret or interactive data. The CLI Adapter renders the prompt, while the MCP Runtime retains Authentication Flow ownership.
+_Avoid_: Daemon stdin, CLI-owned OAuth flow
+
+**Call**:
+One caller-owned request that moves from accepted through queued or active work to exactly one terminal outcome.
+_Avoid_: Detached job, background task
+
+**Schema Cache**:
+Rebuildable knowledge MCPX has observed about server tools and their schemas.
+_Avoid_: Declared tools, registry schema
+
+**Active State**:
+Ephemeral facts about work currently coordinated by the MCP Runtime.
+_Avoid_: Persistent config, runtime registry
+
+**Durable Operational State**:
+Rebuildable or continuity-preserving coordination data that survives MCP Runtime restarts but is neither user intent nor authorization material.
+_Avoid_: Declared Registry, Credential Store

docs/adr/0001-mcpxd-is-the-user-local-mcp-runtime.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: mcpxd Is the User-Local MCP Runtime
+status: accepted
+---
+
+# mcpxd Is the User-Local MCP Runtime
+
+MCPX treats `mcpxd` as the single user-local authority for credential lifecycle, active MCP sessions, and tool-call coordination; the CLI is a stateless adapter. This supersedes the V1/V2 split in which the CLI owned authentication and registry-derived runtime state while the daemon owned only pooled connections, because that split permits competing control decisions across concurrent CLI processes.

docs/adr/0002-runtime-is-the-sole-declared-registry-writer.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: The MCP Runtime Is the Sole Declared Registry Writer
+status: accepted
+---
+
+# The MCP Runtime Is the Sole Declared Registry Writer
+
+All command-driven changes to the Declared Registry go through the MCP Runtime, which is its sole writer. The persisted registry remains inspectable and backup-friendly but is not a supported direct-edit interface; configuration-as-code should use an explicit apply or import operation so external intent cannot race runtime writes.

docs/adr/0003-separate-declared-and-observed-state.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: Separate Declared and Observed State
+status: accepted
+---
+
+# Separate Declared and Observed State
+
+MCPX stores user declarations, authorization material, rebuildable schema knowledge, durable operational state, and active in-memory coordination as distinct classes of state. Derived schema or runtime status must not be written into the Declared Registry, because incidental observations must never contend with or overwrite user intent.

docs/adr/0004-single-flight-authentication-per-credential-identity.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: Single-Flight Authentication per Credential Identity
+status: accepted
+---
+
+# Single-Flight Authentication per Credential Identity
+
+The MCP Runtime permits at most one refresh or interactive Authentication Flow for a Credential Identity. Concurrent callers share its result; disconnecting a caller removes only that waiter, while the final waiter leaving cancels the flow, so concurrent commands cannot rotate the same grant independently or open duplicate authorization pages.

docs/adr/0005-cli-disconnect-cancels-its-call.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: CLI Disconnect Cancels Its Call
+status: accepted
+---
+
+# CLI Disconnect Cancels Its Call
+
+A normal Call is owned by its originating CLI connection: disconnect removes a queued Call or requests cancellation of an active Call, and the MCP Runtime never writes its result to a dead connection. Cancellation is best-effort and does not promise to undo external side effects; detached Calls require a future explicit interface rather than arising accidentally from disconnects.

docs/adr/0006-each-call-owns-its-lifecycle.md

@@ -0,0 +1,9 @@
+---
+type: Decision
+title: Each Call Owns Its Lifecycle
+status: accepted
+---
+
+# Each Call Owns Its Lifecycle
+
+Each Call is the sole authority for its queued, active, and terminal transitions, caller-disconnect cancellation, and lifecycle cleanup. A shared session decides when queued work may proceed but cannot transition or cancel the Call itself, because splitting lifecycle ownership between the CLI connection and session queue permits activation after disconnect and cancellation after completion.

docs/adr/0007-authentication-is-explicit.md

@@ -0,0 +1,13 @@
+---
+type: Decision
+title: Authentication Is Explicit
+status: accepted
+---
+
+# Authentication Is Explicit
+
+An ordinary Call never starts an Authentication Flow. When its Credential Identity is unusable, the MCP Runtime returns `reauth-required`; only an explicit `mcpx @refresh` operation may start or join the single shared flow, so agent and script invocations cannot unexpectedly open a browser or wait for interactive input.
+
+When a provider requires a manually registered OAuth client, the Runtime sends a typed Caller Input request on the active `@refresh` connection. The CLI Adapter owns terminal prompting only; the Runtime owns metadata discovery, single-flight coordination, callback lifetime, token exchange, and persistence. The daemon never reads its ignored stdin, and the CLI never becomes an authentication state machine.
+
+Caller Input is independently cancellable. If its caller disconnects while another waiter remains, the Authentication Flow offers the input request to a surviving waiter; Runtime shutdown aborts the flow and the CLI prompt signal before returning its terminal outcome.

docs/agents/domain.md

@@ -0,0 +1,28 @@
+---
+type: Reference
+title: Domain Documentation
+description: Rules for consuming mcpx domain language and architectural decisions.
+---
+
+# Domain Documentation
+
+This repository uses a single domain context.
+
+## Before Exploring
+
+Read:
+
+- `/CONTEXT.md`, when present.
+- Relevant ADRs under `/docs/adr/`.
+
+Missing files are not errors. `/domain-modeling` creates them lazily when terminology or durable decisions are resolved.
+
+## Vocabulary
+
+Use terms exactly as defined in `CONTEXT.md`. Do not introduce synonyms for established concepts.
+
+If a required concept is absent, either reconsider the new term or record the gap through `/domain-modeling`.
+
+## Architectural Decisions
+
+Surface conflicts with existing ADRs explicitly. Do not silently override an accepted decision.

docs/agents/issue-tracker.md

@@ -0,0 +1,26 @@
+---
+type: Reference
+title: Issue Tracker
+description: GitHub issue workflow used by engineering skills in celados/mcpx.
+---
+
+# Issue Tracker
+
+Issues and build specifications live in `celados/mcpx` GitHub Issues. Use `gh` from this repository so it infers the remote.
+
+## Operations
+
+- Create, read, comment, label, and close issues with `gh issue`.
+- When a skill says “publish to the issue tracker,” create a GitHub issue.
+- When a skill says “fetch the relevant ticket,” read the issue body, comments, and labels.
+- Pull requests are not a triage request surface.
+- Resolve a bare issue or PR number before operating on it.
+
+## Dependencies
+
+Use GitHub native sub-issues and issue dependencies.
+
+- A dependency points from the blocked issue to the blocker.
+- Use the blocker’s numeric database ID, not its issue number or node ID.
+- Fall back to a `Blocked by: #...` line only when native dependencies are unavailable.
+- A ticket is ready only when every blocker is closed.

docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+---
+type: Reference
+title: Triage Labels
+description: Canonical triage roles and their GitHub label mappings.
+---
+
+# Triage Labels
+
+| Role              | GitHub label      | Meaning                          |
+| ----------------- | ----------------- | -------------------------------- |
+| `needs-triage`    | `needs-triage`    | Maintainer evaluation required   |
+| `needs-info`      | `needs-info`      | Waiting for reporter information |
+| `ready-for-agent` | `ready-for-agent` | Fully specified and agent-ready  |
+| `ready-for-human` | `ready-for-human` | Human implementation required    |
+| `wontfix`         | `wontfix`         | Will not be actioned             |

docs/mcpxd-bdd.md

@@ -1,5 +1,14 @@
+---
+type: Specification
+title: mcpxd BDD Spec
+status: superseded
+superseded_by: docs/specs/mcp-runtime-upgrade.md
+---
+
 # mcpxd BDD Spec
 
+> Superseded for architecture and ownership. Retained only as historical regression evidence.
+
 ## Purpose
 
 `mcpxd` is a user-local daemon for reusing stdio MCP server sessions across

docs/mcpxd-v2-bdd.md

@@ -1,5 +1,14 @@
+---
+type: Specification
+title: mcpxd V2 BDD Spec - HTTP routing and first-class notifications
+status: superseded
+superseded_by: docs/specs/mcp-runtime-upgrade.md
+---
+
 # mcpxd V2 BDD Spec - HTTP routing and first-class notifications
 
+> Superseded for architecture and ownership. Retained only as historical regression evidence.
+
 V2 extends V1 in three orthogonal directions:
 
 1. Route HTTP MCP servers through the daemon (session-id preservation + connection reuse).