Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions .github/workflows/checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,27 @@ jobs:
umask 0077
node --test scripts/integrations-mcp.test.mjs scripts/state-snapshot.test.mjs

local-mcp:
name: Local MCP / offline protocol and research boundaries
runs-on: ubuntu-24.04
timeout-minutes: 10
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- name: Install Node runtime dependency
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends libatomic1
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: '26.13.0'
package-manager-cache: false
- name: Install the locked local MCP package
run: npm ci --prefix packages/local-mcp --ignore-scripts --no-audit --no-fund
- name: Test real local MCP transport and synthetic providers
run: npm run test:local

provider-tools:
name: Provider tools / MCP and Playwright
runs-on: ubuntu-24.04
Expand Down
46 changes: 46 additions & 0 deletions Dockerfile.local
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# syntax=docker/dockerfile:1
FROM node:26.13.0-bookworm-slim@sha256:add5c17c14752c54d2f3d519ec46a3815684d41c33f198bcb09fb998f7dcbf68 AS local-base
LABEL org.opencontainers.image.title="Plompy Local MCP" \
org.opencontainers.image.description="Local integration tools for an external MCP client" \
org.opencontainers.image.source="https://github.com/dalkedev/plompy-engine" \
org.opencontainers.image.licenses="MIT"
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates gh libatomic1 tini \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /opt/plompy
COPY packages/local-mcp/package.json packages/local-mcp/package-lock.json ./packages/local-mcp/
RUN npm ci --prefix packages/local-mcp --omit=dev --ignore-scripts --no-audit --no-fund \
&& npm cache clean --force
RUN install -d -m 0700 -o node -g node \
/var/lib/plompy-local /var/lib/plompy-local/config /var/lib/plompy-local/secrets /var/lib/plompy-local/artifacts
ENV NODE_ENV=production \
PLOMPY_LOCAL_CONFIG=/var/lib/plompy-local/config/config.json \
HOME=/tmp/plompy-local-home \
TMPDIR=/tmp
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["node", "packages/local-mcp/server.mjs"]

# Install browser dependencies before application sources so code changes do not
# re-download Chromium. Reuse the locked optional package from the Discord mode.
FROM local-base AS browser-dependencies
COPY packages/playwright/package.json packages/playwright/package-lock.json ./packages/playwright/
ENV PLAYWRIGHT_BROWSERS_PATH=/opt/plompy-browsers
RUN npm ci --prefix packages/playwright --omit=dev --ignore-scripts --no-audit --no-fund \
&& node packages/playwright/node_modules/playwright/cli.js install --with-deps chromium \
&& rm -rf /var/lib/apt/lists/* \
&& npm cache clean --force

FROM local-base AS local
COPY scripts/brand-compat.mjs scripts/integrations.mjs scripts/local-integrations.mjs ./scripts/
COPY scripts/integrations ./scripts/integrations
COPY packages/mcp-bridge/src ./packages/mcp-bridge/src
COPY packages/playwright/package.json packages/playwright/runtime.mjs ./packages/playwright/
COPY packages/local-mcp/server.mjs ./packages/local-mcp/
COPY packages/local-mcp/src ./packages/local-mcp/src
COPY LICENSE ./LICENSE
USER node:node

# The smaller core image has no browser binaries or system browser libraries.
FROM browser-dependencies AS local-browser
COPY --from=local /opt/plompy /opt/plompy
USER node:node
25 changes: 25 additions & 0 deletions Dockerfile.local.dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Strict build allowlist. No host state, credentials, artifacts, Git or test fixtures.
**
!Dockerfile.local
!Dockerfile.local.dockerignore
!LICENSE
!scripts/
!scripts/brand-compat.mjs
!scripts/integrations.mjs
!scripts/local-integrations.mjs
!scripts/integrations/
!scripts/integrations/**
!packages/
!packages/local-mcp/
!packages/local-mcp/package.json
!packages/local-mcp/package-lock.json
!packages/local-mcp/server.mjs
!packages/local-mcp/src/
!packages/local-mcp/src/**
!packages/mcp-bridge/
!packages/mcp-bridge/src/
!packages/mcp-bridge/src/**
!packages/playwright/
!packages/playwright/package.json
!packages/playwright/package-lock.json
!packages/playwright/runtime.mjs
35 changes: 35 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,41 @@ mean starting the conversation again.

Your phone can go back in your pocket.

## Local tools for your own agent

The new **Plompy Local** mode gives an independently running Codex CLI, Claude Code,
OpenCode or compatible MCP client selected research tools through an authenticated
Streamable HTTP endpoint. Start it in Docker, connect your client, and keep the
conversation and model choice in that client. No Discord bot or second model account
is required inside the container. The existing Discord mode remains available.

- Read public sources with bounded HTTP fetching or optional sandboxed Chromium.
- Select supported search/documentation integrations using your own credentials.
- Save sourced research, email drafts, CSV, JSON and Markdown in a persistent volume.
- Use a compatible local model through Ollama in your agent, or choose its supported
hosted provider. Ollama is the model provider, not the MCP client. Local-model
quality and tool calling depend on the chosen model; hosted integrations still
receive their requests.

This mode is **unreleased source**. Build the checked-out source locally; the existing
`0.12.0` image does not contain it. It does not expose email sending or general shell
execution tools. Paid provider calls and actual Ollama inference have not been tested.

[Docker quickstart](docs/local/quickstart.md) · [Codex CLI](docs/local/codex.md) ·
[Claude Code](docs/local/claude-code.md) · [OpenCode](docs/local/opencode.md) ·
[Ollama](docs/local/ollama.md) · [Integration matrix](docs/local/integrations.md) ·
[Verification and limits](docs/local/compatibility.md)

```sh
docker compose -f compose.local.yaml build local
docker compose -f compose.local.yaml run --rm -T local node scripts/integrations.mjs init --mode local
docker compose -f compose.local.yaml up -d local
docker compose -f compose.local.yaml exec -T local node scripts/integrations.mjs test --mode local
```

Use the quickstart to export the access token into your client's environment, select
integrations, and print the appropriate client configuration without embedding secrets.

> Upgrading an existing installation? Read the [0.12 migration guide](docs/migration-plompy.md) before changing service paths or Docker volumes.


Expand Down
54 changes: 54 additions & 0 deletions compose.local.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: plompy-local

x-local: &local
user: "1000:1000"
read_only: true
cap_drop: [ALL]
security_opt:
- no-new-privileges:true
# Chromium's sandbox needs user namespaces and a proc-based chroot. These
# syscalls are allowed without privileged mode or container capabilities.
- seccomp=./scripts/docker-browser-seccomp.json
ports:
- "127.0.0.1:7331:7331"
environment:
PLOMPY_LOCAL_CONFIG: /var/lib/plompy-local/config/config.json
volumes:
- local-config:/var/lib/plompy-local/config
- local-secrets:/var/lib/plompy-local/secrets
- local-artifacts:/var/lib/plompy-local/artifacts
tmpfs:
- /tmp:rw,nosuid,nodev,size=512m,mode=1777
shm_size: 256m
stop_grace_period: 30s
pids_limit: 256
mem_limit: 1g
restart: unless-stopped
logging:
driver: json-file
options:
max-size: "5m"
max-file: "2"

services:
local:
<<: *local
image: plompy-local:development
build:
context: .
dockerfile: Dockerfile.local
target: local
local-browser:
<<: *local
profiles: [browser]
image: plompy-local-browser:development
build:
context: .
dockerfile: Dockerfile.local
target: local-browser
mem_limit: 2g

volumes:
local-config:
local-secrets:
local-artifacts:
64 changes: 64 additions & 0 deletions docs/adr/0001-local-mcp.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# ADR 0001: Separate local MCP tools from Discord agent execution

Status: accepted for the unreleased local implementation

Date: 2026-11-12

## Context

The existing engine owns Discord conversations, runner sessions, jobs and recovery.
Its Docker image installs Codex and does not expose a tool server. A user with an
existing local coding agent needs tools without a second agent, Discord account or
model account inside the container.

## Decision

Add a small ESM package using the same locked official MCP SDK as the credential
bridge. Expose authenticated Streamable HTTP at `/mcp`. The external client owns
reasoning, model selection and its own permissions. Plompy owns the configured
tool allowlist, bounded network access, private credentials and durable artifacts.

Keep the Discord entry point, its Compose file and runner adapters unchanged.
Reuse the integration catalog, vendor endpoint definitions, credential validation,
and pinned Playwright installation. Extend the existing integration CLI with
`--mode local` instead of creating a competing setup experience.

Provide a lightweight image and an optional Chromium image. Both run as UID 1000,
publish only host loopback, and use separate persistent configuration, secret and
artifact volumes. The browser keeps Chromium's sandbox, routes reads through the
DNS-pinned HTTP adapter, and blocks raw networking with a dead proxy. It exposes
page reading, not unrestricted clicking or code execution.

## Alternatives

1. Run OpenCode inside the existing engine image. Rejected: it couples this mode to
runner/Discord lifecycle and duplicates the user's agent and model account.
2. Forward every upstream tool. Rejected: names and read-only annotations do not
prevent form submissions, embedded browser actions or arbitrary side effects.
3. Build a general service platform with users, billing and a hosted control plane.
Rejected: unnecessary for a local open-source tools service.

## Consequences

The same endpoint works independently of the model provider. Codex, Claude Code and
OpenCode receive separate configuration examples. Ollama, when supported by the
chosen client and model, is configured in that client, not inside Plompy.

The initial research profile intentionally excludes arbitrary custom MCP servers,
TinyFish autonomous actions and Camoufox. Existing runner integrations remain
available in their original mode. Remote search needs the operator's provider and
may incur provider charges. No data-locality promise is inferred from Docker or
from choosing a local model.

Stateless HTTP is sufficient for bounded request/response tools. There are no
background MCP tasks, sampling or OAuth delegation. Disconnect/deadline signals
cancel supported operations; remote completion is not reversible and calls are
never replayed automatically. Operators restart after changing configuration.

## Verification

Use package tests for protocol, permission boundaries, provider failures, private
paths, redaction and idempotent export. The Docker acceptance suite checks real
sandboxed rendering and persistence. Actual client tests use isolated configuration
and a deterministic local model fixture, clearly separate from real model quality
or paid provider testing. See the [acceptance instructions](../../packages/local-mcp/test/README.md).
5 changes: 5 additions & 0 deletions docs/docker.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Docker deployment

This page covers the existing Discord engine container. For the separate local
integration server used by Codex CLI, Claude Code, OpenCode and other MCP clients,
see [Plompy Local Docker quickstart](local/quickstart.md). The local mode starts
without Discord or a model account inside the container.

For installations created before 0.12, follow the [Plompy migration guide](migration-plompy.md) and use `compose.legacy.yaml` to retain existing volumes. Do not initialize empty replacement volumes.

This image packages and verifies **Codex only**. `PLOMPY_RUNNER` must be `codex`;
Expand Down
9 changes: 9 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,15 @@ your own Linux machine. The public edition runs one shared worker. Start with Co
Claude Code and OpenCode are experimental host adapters, and the published Docker
image supports Codex only.

## Local MCP preview

[Plompy Local](local/introduction.md) adds selected tools in Docker for a host agent,
without Discord setup. Start with the [local Docker quickstart](local/quickstart.md),
then [connect Codex, Claude Code, OpenCode or another MCP client](local/other-clients.md).
[Ollama](local/ollama.md) is an optional local model provider for a compatible agent.
This source-built preview is separate from the published 0.12.0 Discord image;
read the [verification record](local/compatibility.md) for tested boundaries.

## Start here

1. Follow the [quick start](../README.md#quick-start) to build the engine, initialize a
Expand Down
44 changes: 44 additions & 0 deletions docs/local/architecture.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# One conversation. Selected tools.

The local mode follows a single agent loop:

```text
You -> Codex / Claude Code / OpenCode / another MCP client
-> MCP over loopback HTTP
-> Plompy Local in Docker
-> enabled read tools
-> optional external integrations
-> private artifact volume
<- tool results and source URLs
You <- response, evidence and saved files
```

## Your client decides what to do

The host client owns the conversation, model selection, planning and tool choice. Its own permissions still apply. Adding Plompy does not remove your client's existing tools or isolate its shell.

## Plompy exposes a small tool surface

The gateway validates requests, authenticates the client, exposes only selected tools and enforces bounded calls. It does not offer a generic shell, browser script executor or arbitrary integration invocation tool.

The standard MCP SDK handles initialization, discovery and calls over Streamable HTTP at `/mcp`. The gateway has no Discord connection and does not load the engine's runner authentication.

## Integrations remain separate

The existing catalog identifies supported services. Local mode adds an explicit research policy on top: a configured service and an allowed tool name are both required. A missing or failing integration is reported separately; it does not make unrelated local tools unavailable.

API-key services reuse the fixed vendor definitions and private credential handling from Plompy's existing MCP bridge. GitHub uses a dedicated read adapter for `gh`. It is not treated as an existing MCP server.

## Files survive container replacement

Configuration, secrets and artifacts use separate named volumes. A rebuilt image does not remove them. Do not run Compose with volume deletion unless you intend to erase that data. See [Backups and updates](maintenance.md).

## Where code lives

- Engine and canonical Markdown: [dalkedev/plompy-engine](https://github.com/dalkedev/plompy-engine).
- Local gateway: `packages/local-mcp/`.
- CLI: `scripts/local-integrations.mjs`, reached through the existing integrations command.
- Local containers: `Dockerfile.local` and `compose.local.yaml`.
- Website: the existing static Plompy site, built from HTML, CSS and JavaScript. Documentation pages are generated from the engine's `docs/local/` Markdown.

A copy of documentation in a browser is not a connection to a local gateway. The website never requests your integration keys or automatically contacts localhost.
43 changes: 43 additions & 0 deletions docs/local/artifacts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Results you can inspect

The local artifact tools store files in the dedicated artifact volume. Use JSON for structured evidence, CSV for a spreadsheet, and Markdown for a readable summary or drafts.

## Export a result

Ask your host agent to use `artifacts_export` with a descriptive basename and the matching format. CSV and JSON accept structured records. Markdown accepts text content.

```text
Save the sourced company records as companies.json and companies.csv.
Save the draft messages and any unresolved gaps as drafts.md.
Use the artifact tools, not arbitrary shell writes.
```

## File rules

Names are flat basenames inside the configured artifact directory. Traversal paths and symlink targets are rejected. The tool does not overwrite an unrelated file. Repeating an identical export can return the existing result; changing the content requires a new name.

Exports are bounded. Split a large result into explicit batches instead of asking the model to bypass limits. The response includes a file name, size and content hash so you can identify the output.

## CSV handling

CSV values that could be interpreted as spreadsheet formulas are escaped. This protects exported text such as a company name beginning with `=`. Normal CSV quoting alone does not provide that protection.

Keep source URLs and evidence status in the export. Do not include credentials, session cookies or private account contents.

## List and read

Use `artifacts_list` to discover saved files and `artifacts_read` to inspect a file. Readback checks that the intended result exists; a tool's queue receipt is not a completed file export.

## Retrieve files on the host

The files remain in a Docker volume until you copy them out. From your host, create a new private directory and copy only the artifact directory:

```sh
mkdir -m 700 plompy-results
docker compose -f compose.local.yaml cp \
local:/var/lib/plompy-local/artifacts/. ./plompy-results/
```

Use `local-browser` if that is the running service. Choose a new destination instead of overwriting an existing result directory. Do not mount your entire home directory to make retrieval easier.

For backups and cleanup, see [Updates, backup and uninstall](maintenance.md).
Loading