开源MCP工具

Installation

Prerequisites

• Go - same minor version as go.mod (currently 1.25).
• Git - used by the Makefile for the embedded version string.
• Node.js / npm - only if you build with http and ui (the Makefile runs ui-build for embedded assets).

Install with Go (quick, default upstream tags)

go install github.com/EvilFreelancer/coddy-agent/cmd/coddy@latest

That builds whatever the module ships without custom -tags. For coddy http, the bundled SPA, scheduler, and long-term memory together, build from source with the tags below (same defaults as Dockerfile / docker-compose.dev.yml).

Recommended full binary from source (HTTP + UI + scheduler + memory)

Pass the memory build tag to link long-term memory; optional HTTP, SPA, and scheduler use their own tags (see Build tags). Runtime memory.enabled in YAML only applies when the binary includes memory.

git clone https://github.com/EvilFreelancer/coddy-agent
cd coddy-agent
make build TAGS="http ui scheduler memory"

The CLI is written to build/coddy (not the repo root).

Install build/coddy onto your PATH

Reuses build/coddy when it already exists; otherwise builds with all optional modules first.

make build TAGS="http ui scheduler memory"
make install

• root - /usr/local/bin/coddy
• regular user - ~/.local/bin/coddy (put that directory on PATH if needed)

Build without installing

make build TAGS="http ui scheduler memory"

Manual go build (same as Makefile)

When TAGS includes http and ui, run make ui-build first (or rely on make build, which triggers it).

make ui-build   # required before go build when using -tags=...,ui,... with http
VERSION="$(make -s print-version)"
go build -tags=http,ui,scheduler,memory \
  -ldflags "-X github.com/EvilFreelancer/coddy-agent/internal/version.Version=${VERSION}" \
  -o build/coddy \
  ./cmd/coddy/

Lean ACP-only binary (no coddy http, no embedded UI, no scheduler packages):

make build

After any local build, prefer ./build/coddy or make install so you do not accidentally run another coddy already on PATH. Check with which coddy and coddy -v.

Full detail, LDFLAGS, and make print-version - docs/build.md.

The agent speaks ACP over stdio. An ACP client (your editor integration or harness) launches coddy once it is configured to spawn coddy acp. coddy -v or coddy --version prints the embedded build version (dev if not set at link time). Flags for ACP live on the subcommand, for example coddy acp --help (--log-level, --home, --cwd, --config, etc.).

Build tags

Use Makefile variable TAGS with spaces (make build TAGS="http ui scheduler memory"). go build uses commas (-tags=http,ui,scheduler,memory).

Extended narrative and Docker alignment - docs/build.md.

Docker

Release images are published on GitHub Container Registry as ghcr.io/coddy-project/coddy-agent (tags such as latest and X.Y.Z, linux/amd64 and linux/arm64). Each SemVer git tag also gets GitHub Release archives (Linux, Windows, macOS Intel and Apple Silicon) - see docs/build.md. The default image includes http, ui, scheduler, and memory - the same feature set as make build TAGS="http ui scheduler memory".

1. Config and workspace (from the repo root, or any directory where you keep config.yaml):

```bash cp config.example.yaml config.yaml mkdir -p workspace coddy_home

Example harnesses (see examples/README.md): ./examples/build_coddy.sh && ./examples/test_acp.sh && ./examples/test_httpserver.sh

Full-featured local binary (HTTP + UI + scheduler), same defaults as Docker

make build TAGS="http ui scheduler memory"

./build/coddy -v # same as --version

Quick Start

Examples (ACP over stdio)

examples/acp/acp_e2e_todo.py is a newline-delimited JSON-RPC harness against coddy acp ( stdbuf -oL, permission auto-reply, nil-result responses). Use it as reference when building your own minimal client rather than chaining naive echo lines into a pipe.

examples/acp/acp_e2e_memory.py drives build/coddy, an isolated CODDY_HOME, and RPA_API_KEY to verify recall, persist, and optional prune of markdown under $CODDY_HOME/memory. See the script docstring for flags. Overview of all harnesses - examples/README.md.

Single-line sanity check only (responses may omit JSON-RPC "result" for nil payloads; prefer examples/acp/acp_e2e_todo.py)

echo '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}' | coddy acp ```

Edit config.yaml: at least one provider api_key (or rely on OPENAI_API_KEY etc. in compose)

**2. Start with Compose** (pull published image, no local build):

To **build the image locally** instead, use **`docker-compose.dev.yml`**: **`docker compose -f docker-compose.dev.yml up -d --build`**.

**3. Open the bundled UI** in a browser on the host:

The SPA is served on GET / by coddy http. Pick a model in the composer (YAML backends from GET /v1/models), choose agent or plan mode, then send a message - the UI creates a session and streams the reply via POST /v1/responses. Agent files and shell tools use the mounted workspace (./workspace → /workspace in the container). Live YAML editing: http://127.0.0.1:12345/#/settings.

Sanity check without a browser: curl -sS http://127.0.0.1:12345/v1/models | head.

There is no login on the HTTP surface - expose port 12345 only on trusted networks. Full compose options, volumes, and CI image tags: docs/docker.md. Smoke script: examples/httpserver/docker.sh.

Configuration

CODDY_HOME defaults to ~/.coddy. Unless you set CODDY_CONFIG or pass --config, the primary config file is config.yaml at $CODDY_HOME/config.yaml.

Copy the example and edit it:

mkdir -p ~/.coddy && cp config.example.yaml ~/.coddy/config.yaml

If $CODDY_HOME/config.yaml is absent, the loader may use config.yaml in the process working directory (useful when running from a repository clone). See docs/config.md.

Providers and models

• providers - named backends (type: openai for OpenAI and OpenAI-compatible HTTP APIs, anthropic for Anthropic). Each name must be ASCII letters, digits, hyphen, or underscore, starting with a letter (it becomes the prefix in model ids). Each row has api_key (literal, ${ENV} expanded when the file loads, or empty to read NAME_API_KEY from the environment at LLM call time, with NAME derived from providers[].name in uppercase and hyphens mapped to underscores), and optionally api_base when the API is not the vendor default.
• models - selectable models. Each model string is <provider_name>/<api_model_id> where provider_name matches providers[].name. Tunables include max_tokens, temperature, and optional max_context_tokens.
• agent - model picks the default ReAct model (must match one models[].model entry). max_turns and max_tokens_per_turn bound one user turn.

Example (openai provider and gpt-5.4-mini; store secrets in the environment, not in git):

providers:
  - name: openai
    type: openai
    api_key: "${OPENAI_API_KEY}"

models:
  - model: "openai/gpt-5.4-mini"
    max_tokens: 400000
    temperature: 0.2

agent:
  model: "openai/gpt-5.4-mini"
  max_turns: 35
  max_tokens_per_turn: 128000

Then export the key the YAML references:

export OPENAI_API_KEY="sk-..."

Other setups (Anthropic, Ollama, a non-default api_base, and env-based defaults) are covered in config.example.yaml and docs/config.md.

Configuration

Full configuration reference in docs/config.md.

Key settings:

providers:
  - name: local
    type: openai
    api_key: "${OPENAI_API_KEY}"
    api_base: "${OPENAI_API_BASE}"

models:
  - model: "local/gpt-4o"
    max_tokens: 8192
    temperature: 0.2

agent:
  model: "local/gpt-4o"
  max_turns: 30

tools:
  require_permission_for_commands: true

Run with debug logging (ACP mode); optional --log-output, --log-file, --log-format

coddy acp --log-level debug

Editor and IDE integration

Coddy speaks ACP as the server over stdin/stdout. A compatible client must spawn coddy acp and exchange JSON-RPC messages (see docs/acp-protocol.md and examples/acp/).

• Zed and other products that support external ACP agents can point their agent command at coddy acp (exact settings depend on that product; see its ACP or external-agent docs).
• Cursor Desktop (in-app Agent or Composer) does not document a supported way to replace the built-in agent with a custom coddy acp binary. Cursor's published ACP guide describes agent acp, where Cursor's own agent runs as the ACP server for third-party clients (for example Neovim or JetBrains integrations that connect to Cursor). That is the opposite wiring from running Coddy as your local agent process.
• Cursor-style paths on disk - Coddy can still load rules and skills from .cursor/rules/, ~/.cursor/skills, and other skills.dirs entries in config.yaml. That is file-layout compatibility with Cursor, not Cursor acting as the Coddy runtime host.

MCP Server Integration

Connect external tools via MCP servers. Configured globally in config.yaml or passed per-session by the ACP client.

Example adding a GitHub MCP server in config:

mcp_servers:
  - name: "github"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      - name: "GITHUB_PERSONAL_ACCESS_TOKEN"
        value: "${GITHUB_TOKEN}"

See MCP Integration Guide for details.