diff --git a/compose.local.yaml b/compose.local.yaml index be7effc..8446f6c 100644 --- a/compose.local.yaml +++ b/compose.local.yaml @@ -10,9 +10,10 @@ x-local: &local # syscalls are allowed without privileged mode or container capabilities. - seccomp=./scripts/docker-browser-seccomp.json ports: - - "127.0.0.1:7331:7331" + - "127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331" environment: PLOMPY_LOCAL_CONFIG: /var/lib/plompy-local/config/config.json + PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}" volumes: - local-config:/var/lib/plompy-local/config - local-secrets:/var/lib/plompy-local/secrets diff --git a/docs/docker.md b/docs/docker.md index 3da817e..8794739 100644 --- a/docs/docker.md +++ b/docs/docker.md @@ -24,21 +24,31 @@ reproduce. Rebuilding later can pick up newer Debian security packages. ## First start -Install Docker Engine with the Compose plugin. Clone the public source and copy -`.env.example` to an absolute private file **outside** the checkout. Replace the token -and Discord IDs, then restrict the file to your account: +Install Docker Engine with the Compose plugin. Prepare a bot and private forum in +a Discord server you own. The [configuration guide](configuration.md) lists the +required permissions and four Discord IDs. + +Use the stable release checkout to get the engine Compose file: + +```sh +git clone --branch v0.13.0 --depth 1 https://github.com/dalkedev/plompy-engine.git +cd plompy-engine +``` + +Copy `.env.example` to an absolute private file **outside** the checkout. Replace +the token and Discord IDs, then restrict the file to your account: ```sh chmod 600 /absolute/private/plompy.env export PLOMPY_ENV_FILE=/absolute/private/plompy.env export PLOMPY_IMAGE=ghcr.io/dalkedev/plompy-engine:0.13.0 docker compose config --quiet -docker compose pull +docker compose pull engine docker compose run --rm engine init docker compose run --rm engine sandbox-check docker compose run --rm -it engine login docker compose run --rm engine login-status -docker compose up -d --no-build +docker compose up -d --no-build engine docker compose logs --tail=50 engine ``` diff --git a/docs/local/claude-code.md b/docs/local/claude-code.md index 5cfd30f..78c0abf 100644 --- a/docs/local/claude-code.md +++ b/docs/local/claude-code.md @@ -25,7 +25,7 @@ The output is: } ``` -Claude Code expands the environment variable in the header. Preserve the literal `${PLOMPY_LOCAL_TOKEN}` reference when saving JSON; do not expand it into a real token in a shell-generated file. Merge the entry with your existing MCP configuration rather than overwriting it. The generator is print-only. +Claude Code expands the environment variable in the header. Preserve the literal `${PLOMPY_LOCAL_TOKEN}` reference when saving JSON. Merge the entry with your existing MCP configuration. If you use a supported Compose port override, use the URL from the generated fragment in either setup path. ## Register with the CLI diff --git a/docs/local/codex.md b/docs/local/codex.md index 8cf1e2f..5beba0a 100644 --- a/docs/local/codex.md +++ b/docs/local/codex.md @@ -1,6 +1,6 @@ # Connect Codex -Run the [Docker quickstart](quickstart.md) first. Codex stays on your host and uses its own model login. Plompy provides selected tools over the local HTTP endpoint. +Run the [Docker quickstart](quickstart.md) first. This guide covers Codex CLI running on the same machine as Docker. Codex uses its own model login and reaches Plompy tools over the local HTTP endpoint. ## Add the MCP server @@ -30,7 +30,7 @@ url = "http://127.0.0.1:7331/mcp" bearer_token_env_var = "PLOMPY_LOCAL_TOKEN" ``` -Merge it into your private Codex configuration. The generator is print-only; it does not replace a host file or your other servers. +Merge it into your private Codex configuration. The generator prints the endpoint and token reference. For a supported Compose port override, use the URL it prints in either setup path. ## Provide the token privately diff --git a/docs/local/discord.md b/docs/local/discord.md index 7a50838..bc5b3f2 100644 --- a/docs/local/discord.md +++ b/docs/local/discord.md @@ -2,16 +2,24 @@ The original engine accepts tasks from private Discord threads, stores work in a durable queue and launches a coding runner. That deployment uses the engine repository's `compose.yaml`, its private environment file, its runner credentials and its own volumes. +## Start the stable Discord engine + +1. Prepare a Discord bot and a private forum in a server you own. Enable Message Content Intent and copy your server, owner, bot and forum IDs. See [Discord configuration](https://github.com/dalkedev/plompy-engine/blob/main/docs/configuration.md) for permissions. +2. Use Git to clone release `v0.13.0` for its Compose file and follow the [Docker engine first start](https://github.com/dalkedev/plompy-engine/blob/v0.13.0/docs/docker.md#first-start). The Docker image uses Codex. For a Linux service using an experimental Claude Code or OpenCode runner, follow [host deployment](https://github.com/dalkedev/plompy-engine/blob/main/docs/deployment.md). +3. After the structured `ready` event, run the [first private code goal](https://github.com/dalkedev/plompy-engine/blob/main/docs/first-goal.md#use-the-supplied-acceptance-project). + +If you already run the engine, use your existing private environment and volumes. For an upgrade from before 0.12, follow the [migration guide](https://github.com/dalkedev/plompy-engine/blob/main/docs/migration-plompy.md). + +## Personal assistant preview + The [personal assistant preview](personal-assistant.md) adds notes, tasks and one-time reminders in a dedicated thread in the configured private forum. It requires the `1.0.0-alpha.1` engine image and explicit opt-in. -The Local starter kit has its own `compose.yaml` in a separate directory and uses the `local` or `local-browser` service. Source developers use `compose.local.yaml` from the repository. Local mode does not require a Discord token or channel. It does not start, migrate or restart your existing Discord bot. +For MCP tools in a host agent, use the [Local Docker quickstart](quickstart.md). Its `local` or `local-browser` service runs in a separate Compose project with separate private volumes. ## Existing documentation -- [Docker engine setup](https://github.com/dalkedev/plompy-engine/blob/main/docs/docker.md) - [Runner support and boundaries](https://github.com/dalkedev/plompy-engine/blob/main/docs/runners.md) - [Runner integrations](https://github.com/dalkedev/plompy-engine/blob/main/docs/integrations.md) -- [Configuration](https://github.com/dalkedev/plompy-engine/blob/main/docs/configuration.md) - [State backups](https://github.com/dalkedev/plompy-engine/blob/main/docs/state-backups.md) ## Different OpenCode roles @@ -19,7 +27,3 @@ The Local starter kit has its own `compose.yaml` in a separate directory and use In Discord mode, the engine's experimental OpenCode adapter starts the pinned runner to execute a job. In local mode, your independently running OpenCode client calls Plompy's tools. Do not point the host client at an engine-managed private runner directory. Do not copy Discord memory, bot credentials or runner auth into the local artifact volume. - -## No automatic migration - -There is no need to rename the existing environment, move its state or replace its Compose file to try local tools. Enable the new mode alongside it using separate private volumes and the documented loopback port. diff --git a/docs/local/opencode.md b/docs/local/opencode.md index d19347a..f6c5e5a 100644 --- a/docs/local/opencode.md +++ b/docs/local/opencode.md @@ -10,7 +10,7 @@ opencode --version OpenCode V1 places entries directly under `mcp` and uses `enabled`. V2 places them under `mcp.servers` and uses `disabled`. Do not combine these schemas. The existing Discord runner is independently pinned to OpenCode `1.19.5`; that does not upgrade your host client. -Generate the matching fragment: +Generate the matching fragment from the running service. If you use a supported Compose port override, use the returned URL in place of `7331` in the examples. ```sh docker compose exec -T local \ @@ -45,6 +45,7 @@ docker compose exec -T local \ "type": "remote", "url": "http://127.0.0.1:7331/mcp", "oauth": false, + "disabled": false, "headers": { "Authorization": "Bearer {env:PLOMPY_LOCAL_TOKEN}" } diff --git a/docs/local/other-clients.md b/docs/local/other-clients.md index ea18a53..ccbde73 100644 --- a/docs/local/other-clients.md +++ b/docs/local/other-clients.md @@ -18,7 +18,7 @@ The generator commands contain no real token. They do not copy model logins, pro ## Requirements for another client -A compatible client must support MCP Streamable HTTP, the endpoint `http://127.0.0.1:7331/mcp`, and an `Authorization: Bearer` header supplied through its private credential mechanism. It must support MCP initialization, discovery and tool calls. +A compatible client must support MCP Streamable HTTP, the gateway's host endpoint (`http://127.0.0.1:7331/mcp` by default), and an `Authorization: Bearer` header supplied through its private credential mechanism. It must support MCP initialization, discovery and tool calls. Keep the token outside checked-in project configuration. If a client only accepts literal secrets in a shared file or cannot attach an authorization header, do not weaken gateway authentication to make it connect. @@ -30,6 +30,6 @@ Do not publish port 7331 to the internet as a shortcut. Choose a deliberately se ## Test one layer at a time -First run the [gateway protocol check](quickstart.md#check-the-local-protocol). Then verify the client's connection and ask it to call `plompy_status`. Finally enable and test one integration with a small task. +Run the [gateway protocol check](quickstart.md#check-the-local-protocol) and the [host reachability check](quickstart.md#check-the-connection-from-your-host). Then verify the client's connection and ask it to call `plompy_status`. Finally enable and test one integration with a small task. An MCP-compatible label is not evidence that every client version has been tested. Read [Compatibility and verification](compatibility.md) for the exact clients and acceptance limits. diff --git a/docs/local/quickstart.md b/docs/local/quickstart.md index ae6d8a0..a15e165 100644 --- a/docs/local/quickstart.md +++ b/docs/local/quickstart.md @@ -50,9 +50,7 @@ Initialization creates a private configuration and local access token. It preser ## Start the gateway ```sh -docker compose up -d local -docker compose exec -T local \ - node scripts/integrations.mjs status --mode local +docker compose up -d --wait local ``` The default endpoint is `http://127.0.0.1:7331/mcp`. Docker publishes it on host loopback only. The process listens on the container interface so the published port is reachable. A normal browser visit is not a connection test: the endpoint requires MCP and a bearer token. @@ -64,11 +62,22 @@ docker compose exec -T local \ node scripts/integrations.mjs test --mode local ``` -This initializes MCP and calls local status. It deliberately avoids remote tool discovery and does not contact vendors or a model. +This initializes MCP and calls local status inside the container. It uses no model or vendor account. + +## Check the connection from your host + +In the terminal that runs Docker, check whether the published gateway responds: + +```sh +curl --disable --noproxy '*' --silent --show-error --output /dev/null \ + --max-time 10 --write-out 'HTTP %{http_code}\n' http://127.0.0.1:7331/health +``` + +`HTTP 401` is expected for this request without a token. It confirms HTTP reachability from the host. Continue to the client check to verify its authorization. If your kit includes `check-local-host.sh`, `sh check-local-host.sh local` verifies host reachability with the local token and prints the MCP URL. See [Troubleshooting](troubleshooting.md) if either check fails. ## Connect your agent -The gateway is client-neutral. Choose the configuration for your installed client: +Choose the configuration for the local CLI you launch on the same machine as Docker: - [Codex](codex.md): Streamable HTTP with a bearer-token environment reference. - [Claude Code](claude-code.md): HTTP MCP with an environment-based authorization header. @@ -91,6 +100,18 @@ Do not search the web yet. A configured entry, a connected server and a completed tool call are separate checks. A model-powered tool call may consume your client model allowance. +## Save your first result + +Try one known public page with the built-in tools. This example needs no search integration or browser profile: + +```text +Use Plompy's web_fetch to read https://plompy.dev/docs/. Save the page title, +returned source URL and checked_at as one record in plompy-first-result.json +with artifacts_export. Read the saved file with artifacts_read and show me the record. +``` + +The result stays in the Local artifact volume. Use the copy command under [Retrieve your results](#retrieve-your-results) to open it on your host. + ## Add one search integration For a company-research task, enable one search provider. [Firecrawl](integrations/firecrawl.md) supports a limited keyless path and a separately configured API-key path. [Perplexity](integrations/perplexity.md) requires your own API access. Review their costs before running an external test. diff --git a/docs/local/source-build.md b/docs/local/source-build.md index bbb61d0..30e55ec 100644 --- a/docs/local/source-build.md +++ b/docs/local/source-build.md @@ -17,7 +17,24 @@ docker compose -f compose.local.yaml exec -T local \ The repository's `compose.local.yaml` builds `Dockerfile.local` and uses development image names. The repository's plain `compose.yaml` starts the separate Discord engine. Always keep `-f compose.local.yaml` on source-build commands. -The Local source Compose project and downloaded starter kit both use the project name `plompy-local`. Do not start both at once. For an independent development instance, choose a different project name and host port and initialize separate volumes. Do not accidentally reuse production credentials or artifacts. +The Local source Compose project and downloaded starter kit both default to the project name `plompy-local`. Use a different project name and loopback port for an independent development instance with its own volumes. + +## Use a different host port + +This requires a source revision or starter kit that supports `PLOMPY_LOCAL_HOST_PORT`; published 0.13.0 and 1.0.0-alpha.1 use a fixed port. Choose an available TCP port from `1024` to `65535` and set it in the local Compose `.env` file. Use a unique Compose project name for a second instance. For example, with a separate checkout of current source, set: + +```dotenv +COMPOSE_PROJECT_NAME=plompy-local-dev +PLOMPY_LOCAL_HOST_PORT=17331 +``` + +Build and start with `-f compose.local.yaml` as above. To apply the port to a running installation, run `docker compose -f compose.local.yaml up -d --force-recreate local` using its existing project name. Docker still publishes only on `127.0.0.1`. Private config, the access token and artifacts stay in their volumes. Check the actual port and regenerate your client fragment before reconnecting: + +```sh +sh scripts/check-local-host.sh local -f compose.local.yaml +docker compose -f compose.local.yaml exec -T local \ + node scripts/integrations.mjs codex --mode local +``` ## Build the browser variant diff --git a/docs/local/troubleshooting.md b/docs/local/troubleshooting.md index 74210d7..871bd07 100644 --- a/docs/local/troubleshooting.md +++ b/docs/local/troubleshooting.md @@ -4,9 +4,18 @@ Check container startup, MCP authentication, tool discovery and actual tool exec ## Connection refused -Check `docker compose ps` and confirm the selected service is running. Core and browser services share port `7331`; do not start both at once. Confirm that the container listener is reachable through the loopback publication. +Run these on the Docker host from the kit directory: -The host client URL is `http://127.0.0.1:7331/mcp`. Inside a different container, `127.0.0.1` means that other container. This quickstart places the MCP client on the host. +```sh +docker compose ps +docker compose port local 7331 +``` + +Use `local-browser` if that is your selected service. The second command should print a `127.0.0.1` address. Use that host port in your MCP URL. See the [host connection check](quickstart.md#check-the-connection-from-your-host) to test it over HTTP. A client inside another container or on another machine has its own loopback interface. + +## Port already in use + +Core and browser share the same published port and volumes. Stop the variant you are switching away from. The published 0.13.0 and 1.0.0-alpha.1 kits require port `7331` to be free. If you need both an existing application on `7331` and a Plompy gateway, use a [source revision or kit that supports an alternate port](source-build.md#use-a-different-host-port). Keep the loopback binding and regenerate the client fragment after changing the port. ## Unauthorized or forbidden diff --git a/examples/local-release/README.md b/examples/local-release/README.md index d34ec1e..73ff00d 100644 --- a/examples/local-release/README.md +++ b/examples/local-release/README.md @@ -14,13 +14,22 @@ From the directory containing this file and `compose.yaml`: ```sh docker compose pull local docker compose run --rm -T local node scripts/integrations.mjs init --mode local -docker compose up -d local +docker compose up -d --wait local docker compose exec -T local node scripts/integrations.mjs test --mode local +sh check-local-host.sh local ``` The authenticated endpoint is `http://127.0.0.1:7331/mcp`. Only host loopback is published. Private configuration, secrets and artifacts persist in named volumes. -The default diagnostic calls no model or external provider. +The container check initializes MCP and calls `plompy_status`. The host check uses `curl` +to verify the authenticated Docker publication and prints the URL to use in the client. +Both checks run without a model or external provider account. + +If port `7331` is occupied, set `PLOMPY_LOCAL_HOST_PORT=17331` (or another free port +from `1024` to `65535`) in this Compose project's `.env` file before starting it. +For an existing installation, keep its project name and apply the changed port with +`docker compose up -d --force-recreate local`. The access token and results remain +in their volumes. Generate fresh client fragments for the new URL. ## Connect OpenCode @@ -31,9 +40,9 @@ V2 uses a different configuration shape. Print the matching fragment: docker compose exec -T local node scripts/integrations.mjs opencode --client-version v1 --mode local ``` -Merge `opencode-v1.json` into your current `opencode.json` (or use the V2 file for -that client). Preserve existing model, provider, MCP and permission settings. -These files are examples, not a command to overwrite an existing configuration. +Merge the generated fragment into your current `opencode.json`. Use `--client-version v2` +if your client uses that schema. The included example files use the default port. +Preserve existing model, provider, MCP and permission settings. In a private terminal with shell tracing disabled, give the token to the client without displaying or storing it in the project: @@ -44,6 +53,9 @@ opencode ``` Ask OpenCode: "Call plompy_status and report available tools. Do not search yet." +To save a first result using built-in tools, ask it to use `web_fetch` on +`https://plompy.dev/docs/`, export the title and returned URL to +`plompy-first-result.json`, and read the saved file back. Then configure one search integration if the task requires discovery. Your client's model access and each integration's API allowance remain separate. After adding an integration, restart `local` and reconnect your client. @@ -70,6 +82,7 @@ docker compose --profile browser pull local-browser docker compose --profile browser run --rm -T local-browser node scripts/integrations.mjs add playwright --mode local docker compose --profile browser up -d local-browser docker compose exec -T local-browser node scripts/integrations.mjs test --mode local +sh check-local-host.sh local-browser --profile browser ``` Use `local-browser` in subsequent exec/token commands. Chromium's sandbox stays diff --git a/examples/local-release/compose.template.yaml b/examples/local-release/compose.template.yaml index 531409a..78e8deb 100644 --- a/examples/local-release/compose.template.yaml +++ b/examples/local-release/compose.template.yaml @@ -8,9 +8,10 @@ x-local: &local - no-new-privileges:true - seccomp=./docker-browser-seccomp.json ports: - - "127.0.0.1:7331:7331" + - "127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331" environment: PLOMPY_LOCAL_CONFIG: /var/lib/plompy-local/config/config.json + PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}" volumes: - local-config:/var/lib/plompy-local/config - local-secrets:/var/lib/plompy-local/secrets diff --git a/packages/local-mcp/server.mjs b/packages/local-mcp/server.mjs index 154cc1d..edac477 100644 --- a/packages/local-mcp/server.mjs +++ b/packages/local-mcp/server.mjs @@ -1,10 +1,10 @@ -import { loadConfig } from './src/config.mjs'; +import { loadConfig, publishedLoopbackPort } from './src/config.mjs'; import { startServer } from './src/server.mjs'; let instance; try { const config=await loadConfig(); - instance=await startServer(config); + instance=await startServer(config, { publishedPort: publishedLoopbackPort() }); console.log(`Plompy Local listening on port ${config.server.port}. Research tools only; no Discord or model account required.`); } catch { console.error('Plompy Local could not start. Run the local init/status commands and check private config, credential permissions and port availability.'); diff --git a/packages/local-mcp/src/config.mjs b/packages/local-mcp/src/config.mjs index 338c466..1c971f2 100644 --- a/packages/local-mcp/src/config.mjs +++ b/packages/local-mcp/src/config.mjs @@ -8,6 +8,16 @@ export const integrationIds = ['web', 'playwright', 'github', 'perplexity', 'fir const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype; const path = value => typeof value === 'string' && isAbsolute(value) && resolve(value) !== '/' && !/[\x00-\x1f\x7f]/.test(value); const require = (ok, message) => { if (!ok) throw new Error(message); }; + +export function publishedLoopbackPort(env = process.env) { + const value = env.PLOMPY_LOCAL_HOST_PORT; + if (value === undefined || value === '') return undefined; + const port = Number(value); + require(/^\d{4,5}$/.test(value) && String(port) === value && port >= 1024 && port <= 65535, + 'PLOMPY_LOCAL_HOST_PORT must be an integer from 1024 to 65535.'); + return port; +} + export function validateConfig(config) { require(plain(config) && config.schemaVersion === 1, 'Expected Plompy Local configuration schemaVersion 1.'); require(Object.keys(config).every(key => ['schemaVersion','server','tokenFile','artifactsDir','integrations'].includes(key)), 'Unknown local configuration field.'); diff --git a/packages/local-mcp/src/server.mjs b/packages/local-mcp/src/server.mjs index c31bb67..896a01a 100644 --- a/packages/local-mcp/src/server.mjs +++ b/packages/local-mcp/src/server.mjs @@ -11,8 +11,10 @@ import { compileSchema } from './schema.mjs'; import { version } from './version.mjs'; export const limits = {requestBytes:2_097_152,responseBytes:2_097_152,concurrent:4,requestMs:45_000}; -export async function startServer(config, {token:injectedToken,toolOptions={},port:injectedPort,requestMs=limits.requestMs}={}) { +export async function startServer(config, {token:injectedToken,toolOptions={},port:injectedPort,publishedPort,requestMs=limits.requestMs}={}) { validateConfig(config); + const publishedHosts = publishedPort === undefined ? [] : + config.server.allowedHosts.map(host => host.replace(/:\d+$/, `:${publishedPort}`)); const token = injectedToken ?? (await readCredential(config.tokenFile,{excluded:[config.artifactsDir]})).token; if (token.length < 32) throw new Error('Access token must contain at least 32 random characters. Run local init.'); const secrets = new Set([token]); @@ -39,7 +41,8 @@ export async function startServer(config, {token:injectedToken,toolOptions={},po const http=createServer(async(req,res)=>{ // Check authority before bearer credentials. Reject duplicate sensitive headers. const count=name=>req.rawHeaders.filter((part,index)=>index%2===0&&part.toLowerCase()===name).length; - if(count('host')!==1||!config.server.allowedHosts.includes(req.headers.host))return json(res,403,{error:'Host not allowed.'}); + const hostAllowed = config.server.allowedHosts.includes(req.headers.host) || publishedHosts.includes(req.headers.host); + if(count('host')!==1||!hostAllowed)return json(res,403,{error:'Host not allowed.'}); if(count('origin')>1||(req.headers.origin!==undefined&&!config.server.allowedOrigins.includes(req.headers.origin)))return json(res,403,{error:'Origin not allowed.'}); const supplied=Buffer.from(req.headers.authorization??'');const expected=Buffer.from(`Bearer ${token}`); if(count('authorization')!==1||supplied.length!==expected.length||!timingSafeEqual(supplied,expected))return json(res,401,{error:'Valid local bearer token required.'}); diff --git a/packages/local-mcp/test/cli.test.mjs b/packages/local-mcp/test/cli.test.mjs index 0127f89..db06f88 100644 --- a/packages/local-mcp/test/cli.test.mjs +++ b/packages/local-mcp/test/cli.test.mjs @@ -95,6 +95,26 @@ test("Codex and Claude Code exports use their native schemas without revealing s assert.equal(await readFile(target, "utf8"), original); }); +test("client exports use the Compose host port without changing initialized state", async (t) => { + const { invoke, logs, configPath } = await fixture(t); + const before = await readFile(configPath, "utf8"); + const config = JSON.parse(before); + const token = await readFile(config.tokenFile, "utf8"); + const port = { env: { PLOMPY_LOCAL_HOST_PORT: "17331" } }; + await invoke(["init"], port); + for (const args of [["codex"], ["claude-code"], ["opencode", "--client-version", "v1"], ["opencode", "--client-version", "v2"]]) { + await invoke(args, port); + assert.ok(logs.at(-1).includes("http://127.0.0.1:17331/mcp")); + assert.ok(!logs.at(-1).includes(token.trim())); + } + await invoke(["codex"]); + assert.ok(logs.at(-1).includes("http://127.0.0.1:7331/mcp")); + assert.equal(await readFile(configPath, "utf8"), before); + assert.equal(await readFile(config.tokenFile, "utf8"), token); + for (const value of ["80", "65536", "07331", "1e4", "0.0.0.0:7331"]) + await assert.rejects(invoke(["codex"], { env: { PLOMPY_LOCAL_HOST_PORT: value } }), /PLOMPY_LOCAL_HOST_PORT/); +}); + test("explicit OpenCode write preserves unrelated keys and private backup, refuses JSONC and schema conflicts", async (t) => { const { root, invoke, logs } = await fixture(t); const target = join(root, "opencode.json"); @@ -139,7 +159,7 @@ test("local diagnostic calls real authenticated MCP status without discovering r config.server.port = service.address.port; config.server.allowedHosts = [`127.0.0.1:${service.address.port}`]; await writeFile(configPath, JSON.stringify(config), { mode: 0o600 }); - await invoke(["test"]); + await invoke(["test"], { env: { PLOMPY_LOCAL_HOST_PORT: "17331" } }); const status = JSON.parse(logs.at(-1)); assert.equal(status.state, "available"); assert.deepEqual(status.checks, ["authenticated MCP initialization", "local status tool"]); diff --git a/packages/local-mcp/test/server.test.mjs b/packages/local-mcp/test/server.test.mjs index a4cfbce..1a2470a 100644 --- a/packages/local-mcp/test/server.test.mjs +++ b/packages/local-mcp/test/server.test.mjs @@ -14,7 +14,7 @@ async function setup(t, options={}) { const root=await mkdtemp(join(await realpath(tmpdir()),'plompy-local-server-')); const config={schemaVersion:1,server:{host:'127.0.0.1',port:7331,allowedHosts:['127.0.0.1:7331'],allowedOrigins:[]},tokenFile:join(root,'secrets','token'),artifactsDir:join(root,'artifacts'),integrations:{web:{enabled:true},...options.integrations}}; await mkdir(config.artifactsDir,{mode:0o700}); - const instance=await startServer(config,{token,port:0,toolOptions:options.toolOptions,requestMs:options.requestMs}); + const instance=await startServer(config,{token,port:0,publishedPort:options.publishedPort,toolOptions:options.toolOptions,requestMs:options.requestMs}); const origin=`http://127.0.0.1:${instance.address.port}`; config.server.allowedHosts=[new URL(origin).host]; const clients=[]; @@ -47,6 +47,22 @@ test('auth, Host, Origin, exact endpoint, methods and JSON limits fail closed',a assert.equal((await fetch(origin+'/mcp',{method:'POST',headers,body:'bad-json'})).status,400); assert.equal((await fetch(origin+'/mcp',{method:'POST',headers,body:JSON.stringify({data:'x'.repeat(2_097_152)})})).status,413); }); +test('the published port accepts only configured loopback authorities and still requires auth', async t => { + const { origin } = await setup(t, { publishedPort: 17331 }); + const health = (host, headers = {}) => new Promise((resolve, reject) => { + const request = httpRequest(`${origin}/health`, { headers: { Host: host, ...headers } }, response => { + response.resume(); + resolve(response.statusCode); + }); + request.on('error', reject).end(); + }); + const auth = { Authorization: `Bearer ${token}` }; + assert.equal(await health('127.0.0.1:17331', auth), 200); + assert.equal(await health('127.0.0.1:17331'), 401); + assert.equal(await health('127.0.0.1:17331', { ...auth, Origin: 'http://127.0.0.1:17331' }), 403); + assert.equal(await health('localhost:17331', auth), 403); + assert.equal(await health('example.test:17331', auth), 403); +}); test('unknown tools, incorrect schemas, paths and credential export are refused',async t=>{ const {connect}=await setup(t);const client=await connect(); for(const request of [ diff --git a/scripts/check-local-host.sh b/scripts/check-local-host.sh new file mode 100644 index 0000000..c6a13cc --- /dev/null +++ b/scripts/check-local-host.sh @@ -0,0 +1,41 @@ +#!/bin/sh +set +x +set -eu + +fail() { + printf '%s\n' "$1" >&2 + exit 1 +} + +service=${1:-local} +if [ "$#" -gt 0 ]; then shift; fi +case "$service" in + local|local-browser) ;; + *) fail 'Usage: sh check-local-host.sh local|local-browser [Compose options]' ;; +esac + +published=$(docker compose "$@" port "$service" 7331) || + fail "Start the $service service before checking its host endpoint." +port=${published#127.0.0.1:} +case "$port" in + ''|*[!0-9]*) fail 'Expected an IPv4 loopback publication for the gateway.' ;; +esac +[ "$port" -ge 1024 ] && [ "$port" -le 65535 ] || + fail 'Expected a published host port from 1024 to 65535.' + +# Pass the header over stdin so the bearer token stays out of the host command +# line, temporary files and output. Ignore .curlrc and all proxy settings. +result=$( + docker compose "$@" exec -T "$service" node --input-type=module -e ' + import { loadConfig } from "./packages/local-mcp/src/config.mjs"; + import { readCredential } from "./packages/mcp-bridge/src/credential.mjs"; + const config = await loadConfig(); + const { token } = await readCredential(config.tokenFile, { excluded: [config.artifactsDir] }); + process.stdout.write(`Authorization: Bearer ${token}\n`); + ' | curl --disable --noproxy '*' --proto '=http' --fail --silent --show-error \ + --max-time 10 --header @- "http://127.0.0.1:$port/health" +) || fail 'Host check failed. Check the Compose service, its loopback port and local credentials.' + +[ "$result" = '{"status":"ready","profile":"research"}' ] || + fail 'The published port did not return Plompy Local readiness.' +printf 'Authenticated gateway reached from the host. MCP URL: http://127.0.0.1:%s/mcp\n' "$port" diff --git a/scripts/local-integrations.mjs b/scripts/local-integrations.mjs index 9403207..70b3bcb 100644 --- a/scripts/local-integrations.mjs +++ b/scripts/local-integrations.mjs @@ -4,7 +4,7 @@ import { randomBytes, randomUUID } from "node:crypto"; import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { createRequire } from "node:module"; -import { DEFAULT_CONFIG, integrationIds, loadConfig, validateConfig } from "../packages/local-mcp/src/config.mjs"; +import { DEFAULT_CONFIG, integrationIds, loadConfig, publishedLoopbackPort, validateConfig } from "../packages/local-mcp/src/config.mjs"; import { version } from "../packages/local-mcp/src/version.mjs"; const publicRoot = fileURLToPath(new URL("../", import.meta.url)); @@ -133,9 +133,9 @@ async function stdinSecret() { return secretText(value); } -function configFragment(config, version) { +function configFragment(url, version) { if (!["v1", "v2"].includes(version)) fail("Choose --client-version v1 or v2 explicitly; configuration schemas differ."); - const server = { type: "remote", url: `http://127.0.0.1:${config.server.port}/mcp`, oauth: false, + const server = { type: "remote", url, oauth: false, headers: { Authorization: "Bearer {env:PLOMPY_LOCAL_TOKEN}" }, ...(version === "v1" ? { enabled: true } : { disabled: false }) }; return version === "v1" ? { mcp: { plompy: server } } : { mcp: { servers: { plompy: server } } }; @@ -231,6 +231,7 @@ export async function runLocalIntegrations(argv, { env = process.env, print = (v if (!action || flags.help) { print(help); return; } if (id && !integrationIds.includes(id)) fail("Unknown integration. Use status to see the registered catalog."); if (!["init", "status", "add", "remove", "credential", "opencode", "codex", "claude-code", "sample", "test"].includes(action)) fail("Unknown local command. Use --help."); + const hostPort = publishedLoopbackPort(env); const configPath = resolve(flags.config || (flags.root ? join(flags.root, "config", "config.json") : (env.PLOMPY_LOCAL_CONFIG || DEFAULT_CONFIG))); if ((flags.config && !isAbsolute(flags.config)) || (flags.root && !isAbsolute(flags.root))) fail("Configuration paths must be absolute."); if (action === "sample") { @@ -271,16 +272,16 @@ export async function runLocalIntegrations(argv, { env = process.env, print = (v } const before = await privateFile(configPath); const config = await loadConfig(configPath); + const clientUrl = `http://127.0.0.1:${hostPort ?? config.server.port}/mcp`; if (action === "status") { print(encode(await offlineStatus(config, id))); return; } if (action === "codex" || action === "claude-code") { if (flags.write || flags.replace) fail("This client export is print-only. Merge the fragment into your existing configuration; no file was changed."); - const url = `http://127.0.0.1:${config.server.port}/mcp`; - if (action === "codex") print(`[mcp_servers.plompy]\nurl = "${url}"\nbearer_token_env_var = "PLOMPY_LOCAL_TOKEN"\n`); - else print(encode({ mcpServers: { plompy: { type: "http", url, headers: { Authorization: "Bearer ${PLOMPY_LOCAL_TOKEN}" } } } })); + if (action === "codex") print(`[mcp_servers.plompy]\nurl = "${clientUrl}"\nbearer_token_env_var = "PLOMPY_LOCAL_TOKEN"\n`); + else print(encode({ mcpServers: { plompy: { type: "http", url: clientUrl, headers: { Authorization: "Bearer ${PLOMPY_LOCAL_TOKEN}" } } } })); return; } if (action === "opencode") { - const fragment = configFragment(config, flags["client-version"]); + const fragment = configFragment(clientUrl, flags["client-version"]); if (flags.write) await writeOpenCode(flags.write, fragment, flags["client-version"], flags.replace, print); else print(encode(fragment)); return; diff --git a/scripts/package-local-release.mjs b/scripts/package-local-release.mjs index e4197de..365e830 100644 --- a/scripts/package-local-release.mjs +++ b/scripts/package-local-release.mjs @@ -14,6 +14,7 @@ const sources = { 'compose.yaml': 'examples/local-release/compose.template.yaml', 'compose.apparmor.yaml': 'examples/local-release/compose.apparmor.yaml', 'README.md': 'examples/local-release/README.md', + 'check-local-host.sh': 'scripts/check-local-host.sh', 'opencode-v1.json': 'examples/local-release/opencode-v1.json', 'opencode-v2.json': 'examples/local-release/opencode-v2.json', 'codex.toml': 'examples/local-release/codex.toml', diff --git a/scripts/package-local-release.test.mjs b/scripts/package-local-release.test.mjs index 7fc3014..3160da6 100644 --- a/scripts/package-local-release.test.mjs +++ b/scripts/package-local-release.test.mjs @@ -23,9 +23,11 @@ test('standalone download contains only allowlisted public files, pinned images const compose = await file('compose.yaml'); assert.match(compose, /^name: plompy-local/m); assert.ok(compose.includes(`ghcr.io/dalkedev/plompy-engine:${result.version}-local-browser`)); - assert.ok(compose.includes('127.0.0.1:7331:7331')); + assert.ok(compose.includes('127.0.0.1:${PLOMPY_LOCAL_HOST_PORT:-7331}:7331')); + assert.ok(compose.includes('PLOMPY_LOCAL_HOST_PORT: "${PLOMPY_LOCAL_HOST_PORT:-}"')); assert.ok(!/\bbuild:|@VERSION@|docker\.sock|privileged:\s*true/.test(compose)); assert.ok(listing.includes('docker-browser-seccomp.json') && listing.includes('docker-local-apparmor')); + assert.ok(listing.includes('check-local-host.sh')); const v1 = JSON.parse(await file('opencode-v1.json')); assert.equal(v1.mcp.plompy.headers.Authorization, 'Bearer {env:PLOMPY_LOCAL_TOKEN}'); const v2 = JSON.parse(await file('opencode-v2.json'));