agent-host-mcp 0.1.0__tar.gz

agent_host_mcp-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+.pytest_cache/
+dist/
+*.egg-info/
+
+build/
+
+.env
+.env.*
+!.env.example
+
+.uv/
+
+node_modules/
+.tools/

agent_host_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12.13

agent_host_mcp-0.1.0/Makefile

@@ -0,0 +1,48 @@
+.DEFAULT_GOAL := build
+
+UV ?= uv
+NPM ?= npm
+PYTHON_VERSION := $(shell cat .python-version)
+UV_DIR := $(CURDIR)/.uv
+export UV_CACHE_DIR := $(UV_DIR)/cache
+export UV_PYTHON_INSTALL_DIR := $(UV_DIR)/python
+export UV_PROJECT_ENVIRONMENT := $(UV_DIR)/dev
+export UV_MANAGED_PYTHON := true
+export npm_config_cache := $(CURDIR)/.tools/npm-cache
+unexport VIRTUAL_ENV
+
+PORT ?= 7081
+HOST ?= 0.0.0.0
+TEST_HOST ?= 127.0.0.1
+
+.PHONY: python wiki-deps build run test check
+
+python:
+	$(UV) python install --no-bin $(PYTHON_VERSION)
+	$(UV) python find --managed-python --system $(PYTHON_VERSION) > .uv/python-path
+	@case "$$(cat .uv/python-path)" in "$(UV_PYTHON_INSTALL_DIR)"/*) ;; *) echo "Expected a project-local Python under .uv/python" >&2; exit 1 ;; esac
+
+wiki-deps: node_modules/.package-lock.json
+
+node_modules/.package-lock.json: package.json package-lock.json
+	$(NPM) ci --no-audit --no-fund
+
+build: python wiki-deps
+	$(UV) build --python "$$(cat .uv/python-path)" --out-dir build
+	$(UV) export --frozen --no-dev --no-emit-project --output-file build/requirements.txt
+	$(UV) venv --allow-existing --python "$$(cat .uv/python-path)" .uv/venv
+	$(UV) pip uninstall --python .uv/venv/bin/python agent-mcp
+	$(UV) pip install --python .uv/venv/bin/python --reinstall-package agent-host-mcp -r build/requirements.txt $$(ls -t build/agent_host_mcp-*.whl | head -n 1)
+	cp scripts/agent-host-mcp build/agent-host-mcp
+	chmod +x build/agent-host-mcp
+	./.uv/venv/bin/python -m agent_mcp.catalog build/tool-catalog.json
+
+run: build
+	./build/agent-host-mcp --port $(PORT) --host $(HOST)
+
+test:
+	./.uv/venv/bin/python scripts/test_mcp.py http://$(TEST_HOST):$(PORT)/mcp
+
+check: python wiki-deps
+	$(UV) run --frozen --python "$$(cat .uv/python-path)" pytest -q
+

agent_host_mcp-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,242 @@
+# 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).