agent-host-mcp 0.1.0__py3-none-any.whl

agent_host_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: agent-host-mcp
+Version: 0.1.0
+Summary: Connect Codex sessions, remote execution, and project knowledge to MCP clients.
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.12
+Requires-Dist: openai-codex>=0.167.0
+Requires-Dist: python-dotenv<2,>=1
+Requires-Dist: python-multipart<1,>=0.0.33
+Description-Content-Type: text/markdown
+
+# Agent Host MCP
+
+**Turn your agent on the host into an MCP server.**
+
+Agent Host MCP lets your assistant work with the development environment on your
+Linux machine. Read project files, execute Python or shell commands, ask a remote
+Codex agent to carry out a task, and reuse knowledge from past sessions—all
+through one MCP connection.
+
+Use it when your code lives on a remote host and you want your assistant to
+inspect that environment directly instead of copying files and terminal output
+into a conversation.
+
+## What you can do
+
+- **Understand a project:** read contributor guidance, inspect files, and find
+  saved Codex sessions.
+- **Get work done:** run notebook-style Python cells or shell scripts, or delegate
+  a task to Codex in a new or existing session.
+- **Keep useful context:** build topic knowledge from sessions, then browse it in
+  OpenWiki or search it from your assistant.
+- **Manage the host workflow:** transfer files, label sessions, and inspect
+  recorded token usage.
+
+## Quick start
+
+### 1. Start Agent Host MCP on your host
+
+You need a **Linux host**, uv, make, Node.js **22.22.0 or newer**, and npm. Run the
+server as the account whose Codex sessions you want to use, with that account’s
+existing Codex login and configuration. Set `CODEX_HOME` if they live outside
+`~/.codex`. A separate API key is not required by Agent Host MCP.
+
+From a source checkout or an unpacked source release:
+
+```sh
+make build
+```
+
+Create a `.env` file in the directory from which you will start the server:
+
+```dotenv
+MCP_TOKEN=replace-with-a-long-random-secret
+```
+
+Replace the placeholder with a long, randomly generated token. Restrict access:
+
+```sh
+chmod 600 .env
+```
+
+Keep an existing `.env` when upgrading. Keep the token private and provide the
+same value to your client.
+
+Start the server:
+
+```sh
+make run HOST=0.0.0.0 PORT=7081
+```
+
+The CLI is **`agent-host-mcp`**. After building, you can also start it directly:
+
+```sh
+./build/agent-host-mcp --host 0.0.0.0 --port 7081
+```
+
+Use the source-release setup above for all features, including OpenWiki.
+Installing the Python wheel alone does not set up the knowledge viewer.
+
+### 2. Add it to your Codex client
+
+On the machine where you use Codex, set `MCP_TOKEN` to your server’s token. For
+example, in Bash you can enter it without placing its value in shell history:
+
+```bash
+read -rsp 'Agent Host MCP token: ' MCP_TOKEN
+export MCP_TOKEN
+printf '\n'
+```
+
+Register the server, replacing `https://YOUR_HOST` with your server’s HTTPS URL:
+
+```sh
+codex mcp add remotecodex \
+  --url https://YOUR_HOST/mcp \
+  --bearer-token-env-var MCP_TOKEN
+```
+
+Start your Codex client from an environment where `MCP_TOKEN` is available.
+Other MCP clients can use **Streamable HTTP** at `/mcp` with
+`Authorization: Bearer <MCP_TOKEN>`.
+
+### 3. Ask your assistant to use it
+
+Try requests such as:
+
+> Use remotecodex to read AGENTS.md in my project directory and summarize its guidance.
+>
+> Run a Python cell that calculates 6 * 7 on the remote host.
+>
+> Start a new Codex session in my project and ask it to investigate the failing tests.
+>
+> Search my saved knowledge for deployment hints.
+
+Replace “my project directory” with the actual host path. The client discovers
+available tools and their parameters through `tools/list`.
+
+## Choose the right execution tool
+
+| Task | Tool | What to expect |
+| --- | --- | --- |
+| Run code directly | `execute(string, path="~")` | A persistent Python namespace per directory. Variables, imports and functions carry over between cells. |
+| Run a shell script | `execute` with a cell beginning with `!` or `%` | The whole remaining cell runs through `/bin/sh` in the chosen directory. |
+| Delegate work to Codex | `run(path, prompt, session_id=None)` | Omit the ID for a new saved session; supply one to resume that exact session. |
+
+`execute` defaults to the server account’s home directory. `run` requires an
+existing working directory. Use `create_path` to create an absolute directory
+and its missing parents first.
+
+`execute` uses the server’s installed Python packages and normal account
+permissions; it is not a security sandbox. Python variables last until the runtime
+or server restarts. Shell environment/directory changes do not carry over to later
+cells. `run` uses your saved Codex login and configured defaults for new sessions.
+A saved session must be closed in its current Codex client before resuming it here.
+
+### Collect a long-running result
+
+`run`, `execute`, `build_knowledge`, and `delete_session` return an **`action_id`**
+immediately. Save it, then repeat the same tool and original arguments with that
+ID until its status becomes `completed`, `failed`, or `interrupted`.
+
+For example, start a cell:
+
+```json
+{"string":"6 * 7"}
+```
+
+Then call `execute` again with the returned ID:
+
+```json
+{"string":"6 * 7","action_id":"returned-action-id","wait_seconds":20}
+```
+
+Omitting the ID starts new work. Reconnecting never reruns the original task.
+Keep an omitted `path` or `session_id` omitted when reconnecting. Inspect the
+nested `result.status` too: a completed action may contain a failed cell or turn.
+
+A gateway timeout or disconnected client leaves the job running. Each reconnect
+waits at most 20 seconds. SSE carries progress and the final result, rather than
+live stdout or model tokens. Server shutdown interrupts active jobs; they are
+not automatically rerun. Completed results are retained for up to 24 hours,
+subject to a 256-action capacity.
+
+## Build and use your knowledge
+
+Ask your assistant to call `list_models`, choose a supported model and depth,
+then call `build_knowledge`. Supply `session_id` to target one session, or omit it
+for an incremental batch. Unchanged, verified context is reused.
+
+Browse the results at **`/knowledge`** and sign in with your MCP token. The
+OpenWiki page and `wiki_list_pages`, `wiki_search`, and `wiki_read` tools use the
+same saved knowledge. Viewing or searching it does not call a model. Browser
+visualization needs access to OpenWiki’s pinned external library/font CDNs.
+
+While the server runs, it also checks for new or changed session context every
+30 minutes. When idle, it runs a daily maintenance pass that still skips unchanged
+context. Builds use your Codex login and can make model calls.
+
+**Session retirement:** knowledge builds may delete sessions whose working
+directories have been removed, after saving and verifying their knowledge.
+Sessions with existing working directories are preserved by automatic builds.
+`delete_session` explicitly deletes a selected session, including one whose
+working directory exists, only after its current knowledge is verified. Active or changed sessions, and sessions with remaining descendants, are kept.
+
+## Available tools
+
+The server exposes thirteen tools. See the [detailed reference](REFERENCE.md)
+for schemas, limits, outputs and failure handling.
+
+| Tool | Use it to |
+| --- | --- |
+| `list_sessions` | Find saved session IDs, models, depths, working directories and descriptions. |
+| `update_session` | Set a client-managed description; blank text clears it. |
+| `list_models` | Discover supported models and reasoning depths. |
+| `create_path` | Create an absolute host directory and missing parents. |
+| `execute` | Execute Python cells or prefixed shell scripts. |
+| `run` | Start or resume a Codex session and submit a prompt. |
+| `build_knowledge` | Extract reusable knowledge from changed or selected sessions; may retire missing-directory sessions. |
+| `delete_session` | Delete a session only after its current knowledge is saved and verified. |
+| `token_count` | Inspect recorded host/session usage and cache-hit ratios; retired usage appears in `others`. |
+| `get_upload_skill` | Get instructions for authenticated HTTP file uploads. |
+| `wiki_list_pages` | Browse knowledge topic pages with pagination. |
+| `wiki_search` | Find relevant knowledge sections. |
+| `wiki_read` | Read selected sections and their source provenance. |
+
+To transfer a local file, read `get_upload_skill` first. Uploads use a separate
+HTTP `POST /upload` with the same Bearer token, the actual file bytes, and a
+client-selected absolute destination directory. Missing parents are created;
+existing files are never overwritten. The file limit is 100 MiB. Native MCP auth
+does not automatically expose the credential to an agent’s separate HTTP client.
+
+Token usage is recorded session usage, not an exact billing report. Cached and
+reasoning counters are subsets, and `cache_hit_ratio` is cached input divided by
+input; unknown coverage is reported.
+
+## Access and upgrades
+
+The landing page at `/` is public. MCP calls, uploads and knowledge content
+require authentication. Signing in to the knowledge browser does not authorize
+MCP calls or uploads. Connect only clients you trust with the host account’s access.
+
+The server reads `.env` from its working directory; an exported `MCP_TOKEN`
+overrides the file. Restart the server after changing its token.
+
+Keep your `.env`, Codex login and saved sessions when upgrading. Extracted
+knowledge is saved under `~/.agent-mcp/knowledge`; preserve it and the other
+Agent Host MCP data described in the [backup reference](REFERENCE.md#long-running-tool-actions-and-sse).
+Stop the previous service before starting its replacement on the same port,
+then refresh your client’s MCP connection to discover updated tools.
+
+## Check your setup
+
+With the server running and curl installed:
+
+```sh
+make test PORT=7081
+```
+
+This checks the advertised tools, session/model discovery, token accounting and
+wiki retrieval. It does not submit model turns or delete real sessions. It prints
+session and model results, so keep that output private.
+
+| Symptom | What to check |
+| --- | --- |
+| Unauthorized or startup token error | Match the server’s token and the client’s `MCP_TOKEN` environment variable. |
+| Port 7081 is already in use | Stop the intended previous process yourself, or choose another `PORT`. |
+| Session has an active writer | Close its owning Codex session normally before resuming it, or omit the ID to create a separate session. |
+| OpenWiki unavailable | Run `make build` from the source directory and check Node dependencies and browser CDN access. |
+| Client still shows old tools | Refresh/reconnect the client after restarting the updated server; a new conversation alone may not refresh its cache. |
+| Public gateway cannot be reached | Check gateway routing and any IP allowlist separately from the local server. |
+
+For detailed usage, limits and troubleshooting, see [REFERENCE.md](REFERENCE.md).

agent_host_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,35 @@
+agent_mcp/__init__.py,sha256=5zEC3WYJbthOmZ0gNVxhZCALiSoQ4w8gGsjwahMRBb0,37
+agent_mcp/actions.py,sha256=R3Z94Q_9aV0ZU1WIW_wLKjDYRkjlFzIkQOjiYrdnetk,9581
+agent_mcp/auth.py,sha256=DVmlguPHdcxj_XAG8E3AXx4atsrXnw0TxZ0nn88JLAg,3568
+agent_mcp/catalog.py,sha256=EmoTDCWwYeLjZXBcgIuOkyOsx0PgXTDuYvp0wLuxVLY,1710
+agent_mcp/cell_worker.py,sha256=tEs611aJc8Ue3dw1yzK4tbiRe11nFHUHM3X5oJ0g9OA,4642
+agent_mcp/database.py,sha256=Vq2vU8T9zMGOHuEuBejZJ89WpFYhSJJwfYFK8jmbGeU,1143
+agent_mcp/execution.py,sha256=4BWErvCPBEmYxitKzHfDhhnx1ltpR9c2uhuoQwgKjxs,3566
+agent_mcp/knowledge.py,sha256=Ig-xHkP7Pp6jYy5338RMdj84Ib0KbN_jhYD5MshKjOc,6905
+agent_mcp/knowledge_sdk.py,sha256=kFUydoC24yca2WxcIfLkbTQbmtLx66Zs5K4kfTvVX3Y,6755
+agent_mcp/knowledge_store.py,sha256=zPSagOmhk5NULub5w2qlGYud8adaluAVCYottnF6agU,5809
+agent_mcp/landing.html,sha256=VRvXag-_wdpXtA92dsGz8ucZJWHFvmGWQKlMNyUUPGk,6461
+agent_mcp/models.py,sha256=F-L-8NcywC9IYfSd1JFtvyCn09I4c2hvLh8syJKvmW8,2197
+agent_mcp/openwiki_export.mjs,sha256=bBqznHVYTu2xN7fz1fi7veR3RP9URqznSMwhWxHwnv8,326
+agent_mcp/openwiki_retrieve.mjs,sha256=CzQSfp9fg3mWUGyrTbNG_p_YoDOy_cOavZlDvchE7NI,520
+agent_mcp/paths.py,sha256=7MaPSTdBtZJX6mvrL1kPoMn4yk3e6KL3ucp-0cAl0PA,885
+agent_mcp/runner.py,sha256=9aDXXbNjsePWUXCnsD-mxuEpTkMUnsMKYAj1QR0kP0A,6036
+agent_mcp/scheduler.py,sha256=-x3NdFsEDuziEYE9LA10QPK30uCMI3vpgQLLJKr3Gvw,5542
+agent_mcp/server.py,sha256=OqW2fdRv699CRXp8FZ4D1waRkN89an3N0MGr6Nr-PMw,33619
+agent_mcp/session_delete.py,sha256=zWq0GamBH7_9JV9tOtmDDYUzmhO3IUJnKwPKn0UxUUA,3996
+agent_mcp/session_metadata.py,sha256=mTl7FrLpoBGrXGGYs7VYECkeJJ0iRnlyKyrDXMt8q-o,2488
+agent_mcp/sessions.py,sha256=OQs-5Ru11BzfUeM6bAe_w0T7FnVmeXTDrmWk36ER3CY,5697
+agent_mcp/tokens.py,sha256=3hu2y6GxXqIFz9bpBpI9161TXaD8ZXe6tkqtTN2Hr2E,5046
+agent_mcp/upload_routes.py,sha256=etOOLTttYhdQmSrQ5UWbt3wtS5o5vWnVWp-rK8Y4XOs,3730
+agent_mcp/upload_skill.py,sha256=X0q9hBu-e4TL9LJ9p2BXYWxET7pSo8nsjonIPU2k8nk,626
+agent_mcp/uploads.py,sha256=bT7Gy14HkoSM2MBKBxFBI_ybF0NTqM5uekKvLJqd3yg,4613
+agent_mcp/version.py,sha256=O094-OhpGIG3kvVcIGeUvgAg43V1dbC2wVHqDe9EZ7I,1368
+agent_mcp/wiki.py,sha256=aD1t6B4aNZeDHQptZADbN8-UC4rN9O-_brapNa81x1M,7219
+agent_mcp/wiki_routes.py,sha256=YnQ6AsqS1fPU78Q-wUAs0nF2JjesQVt4zKKVdfApHgw,5281
+agent_mcp/wiki_tools.py,sha256=tMCIradQTIitcH9YwH9cts3jyGUVh7JLi7CYl9sKlPg,8127
+agent_mcp/skills/upload-files/SKILL.md,sha256=qgIdGLXu4De1TFrTPxeqSxpoFZwQdGRllOZ07Fskuvg,4126
+agent_mcp/_build_info.json,sha256=hC-0V4vdrGPhn0Q9dB4ma8V7MCcFtXzd8Qx9wgIj61E,150
+agent_host_mcp-0.1.0.dist-info/METADATA,sha256=Ac06AzPr9-05xnXHWEMpwoVOlejO0gDCIpIjYPUAWgM,10949
+agent_host_mcp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+agent_host_mcp-0.1.0.dist-info/entry_points.txt,sha256=xibB2opuL4fZqvVAZbXrldr0PkorHXdU5LG0ufzIzTs,57
+agent_host_mcp-0.1.0.dist-info/RECORD,,

agent_host_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_host_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-host-mcp = agent_mcp.server:main

agent_mcp/__init__.py

@@ -0,0 +1 @@
+"""Local Codex session discovery."""

agent_mcp/_build_info.json

@@ -0,0 +1 @@
+{"base_version": "0.1.0", "version": "0.1.0.20261111103023100757", "build_id": "20261111103023100757", "built_at": "2026-11-11T10:30:23.100757+00:00"}

agent_mcp/actions.py

@@ -0,0 +1,194 @@
+"""Durable action handles; jobs belong to the server, never an HTTP request."""
+
+import asyncio
+from collections.abc import Awaitable, Callable
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+import time
+from typing import Any, Literal
+from uuid import uuid4
+
+from mcp.server.fastmcp.exceptions import ToolError
+from pydantic import BaseModel
+
+from agent_mcp.database import connect, database_path
+
+
+class ActionResult(BaseModel):
+    action_id: str
+    tool: str
+    status: Literal["running", "completed", "failed", "interrupted"]
+    result: dict[str, Any] | None = None
+    error: str | None = None
+    error_code: str | None = None
+    error_stage: str | None = None
+    retry_after_seconds: int | None = None
+
+
+def _process_identity(pid: int) -> str | None:
+    try:
+        # Include Linux process start time to guard against PID reuse.
+        stat = Path(f"/proc/{pid}/stat").read_text().rsplit(")", 1)[1].split()
+        boot = Path("/proc/sys/kernel/random/boot_id").read_text().strip()
+        return f"{boot}:{pid}:{stat[19]}"
+    except (OSError, IndexError):
+        return None
+
+
+def _owner_alive(owner: str) -> bool:
+    try:
+        return _process_identity(int(owner.split(":")[1])) == owner
+    except (IndexError, ValueError):
+        return False
+
+
+class Actions:
+    def __init__(self, path: Path | None = None, *, capacity: int = 256, retention: float = 86400, heartbeat: float = 2):
+        self.path = path if path is not None else database_path()
+        self.capacity, self.retention, self.heartbeat = capacity, retention, heartbeat
+        self.owner = _process_identity(os.getpid())
+        self._jobs: dict[str, asyncio.Task] = {}
+        self._closed = False
+        self._pending_saves: dict[str, ActionResult] = {}
+
+    @staticmethod
+    def _fingerprint(tool: str, arguments: dict) -> str:
+        return hashlib.sha256(json.dumps([tool, arguments], sort_keys=True).encode()).hexdigest()
+
+    def _database(self):
+        return connect(self.path)
+
+    def _prepare(self, db):
+        db.execute("""CREATE TABLE IF NOT EXISTS actions (
+            id TEXT PRIMARY KEY, tool TEXT NOT NULL, fingerprint TEXT NOT NULL,
+            owner TEXT NOT NULL, response TEXT NOT NULL, finished REAL)""")
+        db.execute("DELETE FROM actions WHERE finished IS NOT NULL AND finished <= ?", (time.time() - self.retention,))
+        for row in db.execute("SELECT id, response, owner FROM actions WHERE finished IS NULL").fetchall():
+            if not _owner_alive(row["owner"]):
+                response = ActionResult.model_validate_json(row["response"])
+                response.status = "interrupted"
+                response.retry_after_seconds = None
+                response.error = "Server process stopped; inspect session state before submitting a new action. This action was not rerun."
+                db.execute("UPDATE actions SET response=?, finished=? WHERE id=?",
+                    (response.model_dump_json(), time.time(), row["id"]))
+
+    def start(self, tool: str, arguments: dict, work: Callable[[], Awaitable[BaseModel]]) -> ActionResult:
+        if self._closed:
+            raise ToolError("The server is shutting down; no new action was started.")
+        self._flush_pending_saves()
+        response = ActionResult(action_id=uuid4().hex, tool=tool, status="running", retry_after_seconds=2)
+        with self._database() as db:
+            db.execute("BEGIN IMMEDIATE")
+            self._prepare(db)
+            if db.execute("SELECT count(*) FROM actions").fetchone()[0] >= self.capacity:
+                oldest = db.execute("SELECT id FROM actions WHERE finished IS NOT NULL ORDER BY finished LIMIT 1").fetchone()
+                if oldest is None:
+                    raise ToolError("The server has too many active actions; retry later.")
+                db.execute("DELETE FROM actions WHERE id=?", (oldest["id"],))
+            db.execute("INSERT INTO actions VALUES (?,?,?,?,?,NULL)", (response.action_id, tool,
+                self._fingerprint(tool, arguments), self.owner, response.model_dump_json()))
+        self._jobs[response.action_id] = asyncio.create_task(self._execute(response, work),
+            name="agent-mcp-action-" + response.action_id)
+        return response.model_copy(deep=True)
+
+    def _save(self, response):
+        with self._database() as db:
+            db.execute("UPDATE actions SET response=?, finished=? WHERE id=?",
+                (response.model_dump_json(), time.time(), response.action_id))
+
+    def _flush_pending_saves(self):
+        # A temporary database outage must not leave a finished job permanently
+        # running. Keep its terminal response until a later call can commit it.
+        # New work is refused while these commits fail, bounding retained results
+        # by the existing action capacity and avoiding duplicate side effects.
+        for action_id, response in list(self._pending_saves.items()):
+            self._save(response)
+            del self._pending_saves[action_id]
+
+    async def _execute(self, response, work):
+        try:
+            response.result = (await work()).model_dump(mode="json")
+            response.status = "completed"
+        except asyncio.CancelledError:
+            response.status = "interrupted"
+            response.error = "Server shutdown interrupted this action; inspect session state before retrying."
+            raise
+        except ToolError as error:
+            response.status = "failed"
+            response.error = str(error)
+            response.error_code = getattr(error, "reason", None)
+            response.error_stage = getattr(error, "stage", None)
+        except Exception:
+            response.status = "failed"
+            response.error = "Action failed; private backend diagnostics were withheld."
+        finally:
+            response.retry_after_seconds = None
+            try:
+                self._save(response)
+            except ToolError:
+                self._pending_saves[response.action_id] = response
+                logging.getLogger(__name__).warning(
+                    "Action result persistence failed; terminal response retained in memory for retry. No work will be rerun.")
+            finally:
+                self._jobs.pop(response.action_id, None)
+
+    def _lookup(self, action_id: str, tool: str, arguments: dict) -> ActionResult:
+        self._flush_pending_saves()
+        with self._database() as db:
+            self._prepare(db)
+            row = db.execute("SELECT fingerprint, response FROM actions WHERE id=?", (action_id,)).fetchone()
+            if row is None:
+                raise ToolError("Unknown or expired action_id. No task was started; inspect session state before submitting a new action.")
+            if row["fingerprint"] != self._fingerprint(tool, arguments):
+                raise ToolError("action_id belongs to a different tool or arguments. Repeat the original arguments exactly; no task was started.")
+            return ActionResult.model_validate_json(row["response"])
+
+    async def reconnect(self, action_id: str, tool: str, arguments: dict, *, wait_seconds: float = 20, progress=None) -> ActionResult:
+        if not 0 <= wait_seconds <= 20:
+            raise ToolError("wait_seconds must be between 0 and 20.")
+        response = self._lookup(action_id, tool, arguments)
+        deadline = time.monotonic() + wait_seconds
+        tick = 0
+        while response.status == "running" and time.monotonic() < deadline:
+            if progress is not None:
+                await progress(tick, message=f"Action {action_id} is running; reconnect with the same ID if disconnected.")
+            remaining = max(0, deadline - time.monotonic())
+            task = self._jobs.get(action_id)
+            if task is not None:
+                await asyncio.wait({task}, timeout=min(self.heartbeat, remaining))
+            else:
+                await asyncio.sleep(min(self.heartbeat, remaining))
+            tick += 1
+            response = self._lookup(action_id, tool, arguments)
+        return response
+
+    async def result(self, action_id: str, tool: str, arguments: dict) -> dict:
+        """Internal scheduler/delete joins the same registered tool action."""
+        while True:
+            response = await self.reconnect(action_id, tool, arguments)
+            if response.status == "completed":
+                return response.result
+            if response.status != "running":
+                raise ToolError(response.error or "Action did not complete.")
+
+    async def close(self):
+        self._closed = True
+        tasks = list(self._jobs.items())
+        for _, task in tasks:
+            task.cancel()
+        await asyncio.gather(*(task for _, task in tasks), return_exceptions=True)
+        self._flush_pending_saves()
+        # A task cancelled before entering its coroutine cannot execute its finally.
+        with self._database() as db:
+            self._prepare(db)
+            for action_id, _ in tasks:
+                row = db.execute("SELECT response FROM actions WHERE id=? AND finished IS NULL", (action_id,)).fetchone()
+                if row:
+                    response = ActionResult.model_validate_json(row["response"])
+                    response.status, response.retry_after_seconds = "interrupted", None
+                    response.error = "Server shutdown interrupted this action; inspect session state before retrying."
+                    db.execute("UPDATE actions SET response=?, finished=? WHERE id=?",
+                        (response.model_dump_json(), time.time(), action_id))

agent_mcp/auth.py

@@ -0,0 +1,84 @@
+"""Static Bearer-token authentication for the local MCP HTTP server."""
+
+import hmac
+import os
+from pathlib import Path
+import re
+
+from dotenv import dotenv_values
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+def load_mcp_token(env_file: Path | None = None) -> str:
+    """An exported MCP_TOKEN overrides the current working directory's .env."""
+    token = os.environ.get("MCP_TOKEN")
+    if token is None:
+        token = dotenv_values(env_file or Path.cwd() / ".env", interpolate=False).get("MCP_TOKEN")
+    if not token or not re.fullmatch(r"[A-Za-z0-9._~+/-]+=*", token):
+        raise ValueError("Set a nonempty, valid MCP_TOKEN in .env or the environment before starting agent-host-mcp.")
+    return token
+
+
+class BearerTokenMiddleware:
+    def __init__(self, app: ASGIApp, token: str):
+        self.app = app
+        self.token = token.encode("ascii")
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        path, method = scope.get("path"), scope.get("method")
+        if (scope["type"] != "http"
+                or (path in ("/", "/knowledge", "/knowledge/") and method in ("GET", "HEAD"))
+                or (path == "/knowledge/login" and method == "POST")):
+            await self.app(scope, receive, send)
+            return
+        if path and path.startswith("/knowledge/") and knowledge_authorized(scope, self.token.decode("ascii")):
+            await self.app(scope, receive, send)
+            return
+        headers = [value for name, value in scope.get("headers", []) if name.lower() == b"authorization"]
+        parts = headers[0].split() if len(headers) == 1 else []
+        if (len(parts) != 2 or parts[0].lower() != b"bearer"
+                or not hmac.compare_digest(parts[1], self.token)):
+            response = JSONResponse({"error": "Unauthorized"}, status_code=401,
+                                    headers={"WWW-Authenticate": 'Bearer realm="agent-host-mcp"'})
+            await response(scope, receive, send)
+            return
+        await self.app(scope, receive, send)
+
+
+KNOWLEDGE_COOKIE = "agent_mcp_knowledge"
+KNOWLEDGE_SESSION_SECONDS = 8 * 60 * 60
+
+
+def token_matches(candidate: str, expected: str) -> bool:
+    return hmac.compare_digest(candidate.encode("utf-8"), expected.encode("utf-8"))
+
+
+def knowledge_cookie(token: str) -> str:
+    import hashlib
+    import time
+    expires = str(int(time.time()) + KNOWLEDGE_SESSION_SECONDS)
+    signature = hmac.new(token.encode(), ("knowledge:" + expires).encode(), hashlib.sha256).hexdigest()
+    return expires + "." + signature
+
+
+def valid_knowledge_cookie(value: str, token: str) -> bool:
+    import hashlib
+    import time
+    parts = value.split(".")
+    if len(parts) != 2 or not re.fullmatch(r"[0-9]{1,12}", parts[0]):
+        return False
+    if int(parts[0]) <= time.time():
+        return False
+    signature = hmac.new(token.encode(), ("knowledge:" + parts[0]).encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(parts[1].encode(), signature.encode())
+
+
+def knowledge_authorized(scope: Scope, token: str) -> bool:
+    from starlette.requests import Request
+    headers = [value for key, value in scope.get("headers", []) if key.lower() == b"authorization"]
+    parts = headers[0].split() if len(headers) == 1 else []
+    if len(parts) == 2 and parts[0].lower() == b"bearer" and hmac.compare_digest(parts[1], token.encode()):
+        return True
+    cookie = Request(scope).cookies.get(KNOWLEDGE_COOKIE, "")
+    return valid_knowledge_cookie(cookie, token)

agent_mcp/catalog.py

@@ -0,0 +1,47 @@
+"""Export the registered MCP catalog without executing tools or starting a server."""
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+from dataclasses import asdict
+
+from agent_mcp.server import AuthenticatedMCP, create_server
+
+
+async def describe_tools(server: AuthenticatedMCP) -> dict:
+    return {
+        "catalog_version": 1,
+        **asdict(server.build_info),
+        "server": server.name,
+        "endpoint": "/mcp",
+        "transport": "streamable-http",
+        "authentication": {"scheme": "bearer", "token_environment_variable": "MCP_TOKEN"},
+        "instructions": server.instructions,
+        "tools": [tool.model_dump(mode="json", exclude_none=True, by_alias=True) for tool in await server.list_tools()],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("output", type=Path, help="Destination catalog JSON file")
+    output = parser.parse_args().output
+    # Use a nonsecret auth placeholder so export never depends on deployment
+    # credentials. Constructing metadata does not open a listening server.
+    previous_token = os.environ.get("MCP_TOKEN")
+    os.environ["MCP_TOKEN"] = "catalog-export-only"
+    try:
+        catalog = asyncio.run(describe_tools(create_server()))
+    finally:
+        if previous_token is None:
+            os.environ.pop("MCP_TOKEN", None)
+        else:
+            os.environ["MCP_TOKEN"] = previous_token
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(catalog, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(f"Exported {len(catalog['tools'])} tool definitions to {output}")
+
+
+if __name__ == "__main__":
+    main()