Term MCP DeepSeek

See the command, risk, workspace, and limits before anything runs. Then keep a signed receipt of what actually happened.

Term MCP DeepSeek is a local, approval-first terminal control plane for MCP clients and humans. It gives DeepSeek an isolated advisory role while deterministic policy owns command planning, approval, bounded execution, live events, and signed evidence.

Why this project

Most terminal agents collapse suggestion and execution into one opaque moment. Term MCP DeepSeek makes the boundary visible:

intent → versioned plan → policy decision → human approval → bounded process → signed receipt

• Model text never executes directly.
• Inspect mode is read-only by default.
• Every command is parsed without a shell and scoped to one workspace.
• Pause, resume, cancel, timeout, output limits, and process isolation are first-class states.
• DeepSeek can be absent or offline without disabling local MCP tools.
• Receipts separate command, stdout, stderr, exit code, signal, permission, and signature.
• Shareable exports remove command text, workspace paths, arguments, and output, then receive a new valid signature.

First result in 60 seconds

Requirements: macOS or Linux, Python 3.10–3.13, and pipx.

pipx install "git+https://github.com/OthmaneBlial/[email protected]"
cd /path/to/the/repository/you/want/to/inspect
term-mcp serve

The server prints a one-time bearer token. Open http://127.0.0.1:8000, paste that token, choose Inspect workspace, then select Build plan and Execute.

Expected result: the UI shows a low-risk pwd plan before execution, then a succeeded receipt with exit code 0, separate stdout/stderr, and a verified HMAC signature. No DeepSeek key is required.

Stop the server with Ctrl+C. The generated token and in-memory sessions disappear with the process.

Install from a clone

Use this path when contributing or testing unreleased changes:

git clone https://github.com/OthmaneBlial/term_mcp_deepseek.git
cd term_mcp_deepseek
./startup.sh token
./startup.sh

startup.sh creates .venv, installs the package, and delegates to the same term-mcp CLI used by packaged installations.

Safety boundary

The default is APPROVAL_MODE=inspect with network disabled.

Confirm and trusted modes are not an operating-system sandbox. Test untrusted repositories in a disposable container or VM. Keep WORKSPACE_ROOT narrow, ALLOW_NETWORK=false, and never expose the HTTP service directly to an untrusted network.

Read SECURITY.md and the threat model before enabling a wider command surface.

CLI

term-mcp serve                       production HTTP server (Waitress)
term-mcp serve --debug               Flask development server
term-mcp stdio                       JSON-RPC over STDIO
term-mcp doctor --json               config, permissions, shell, and transport checks
term-mcp doctor --connectivity        optional DeepSeek endpoint check
term-mcp demo                        no-key guided scenarios
term-mcp receipt validate FILE       schema and HMAC validation
term-mcp receipt show FILE           privacy-aware summary
term-mcp recipe validate FILE...     schema and policy validation
term-mcp recipe run FILE             inspect-only recipe execution
term-mcp token                       strong bearer token generator
term-mcp version                     installed version

Run a complete local quality gate with:

./local_ci.sh

Safe recipe catalog

The repository includes five small workflows for repository inspection, test discovery, log inventory, port configuration, and proof of the read-only boundary. Every recipe is schema-versioned, inspect-only, network-free, write-free, bounded, and checked by the production policy before it can run.

term-mcp recipe validate examples/recipes/*.json --workspace .
term-mcp recipe run examples/recipes/inspect-repository.json --workspace .

Browse the recipe catalog and contribution template. CI executes the complete catalog and runs the no-model benchmark.

See the proof gallery for signed, sharing-redacted success, cancellation, and timeout receipts. The three short demos apply the recipes to an unfamiliar repository, a test surface, and local incident evidence.

MCP clients

The server targets modern MCP 2026-07-28 and supports the legacy 2025-11-25 initialize lifecycle. HTTP and STDIO share one dispatcher and tool catalog.

Recommended local STDIO configuration:

{
  "mcpServers": {
    "term-mcp-deepseek": {
      "command": "/absolute/path/to/term-mcp",
      "args": ["stdio"],
      "env": {
        "WORKSPACE_ROOT": "/absolute/path/to/your/project",
        "APPROVAL_MODE": "inspect"
      }
    }
  }
}

STDOUT contains JSON-RPC messages only; diagnostics go to STDERR. See the MCP compatibility matrix for protocol details and dated client evidence.

HTTP and web API

Protected routes require Authorization: Bearer $AUTH_TOKEN. Public routes are intentionally limited to the UI shell, health, demos, static assets, and receipt schema.

The /sessions, /stream, and /chat routes are web compatibility APIs, not separate MCP transports.

Docker

The image uses a pinned Python base, builds wheels in a separate stage, installs without network in the runtime stage, and runs as UID/GID 10001.

export AUTH_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose up --build

Open http://127.0.0.1:8000. The compose workspace mount is read-only because the default mode is inspect. Stop with docker compose down.

Configuration

The no-key defaults are enough for local inspection. Copy .env.example only when persistent configuration is useful:

cp .env.example .env
term-mcp token
term-mcp doctor

Do not commit .env. Add DEEPSEEK_API_KEY only for the optional advisor panel. The complete variable reference and deployment/rollback guidance are in operations.

Project map

Contributing

Small tests, protocol fixtures, safe recipes, accessibility improvements, and client compatibility reports are welcome. Start with CONTRIBUTING.md, run ./local_ci.sh, and include a redacted receipt when a terminal-execution bug produces one.

Security vulnerabilities belong in GitHub private vulnerability reporting, never in a public issue.

License

MIT — see LICENSE.