Archery MCP Server

中文文档

MCP server for the fixed Archery 1.14.0 public API surface. It uses one configured Archery service account and exposes 31 named tools. TOTP setup and save operations are intentionally excluded.

# Requires Go 1.25+ (see .tool-versions)
make build
./bin/archery-mcp-server version

# Start MCP server (stdio, default)
./bin/archery-mcp-server mcp

# List / call tools from the CLI (no MCP client required)
./bin/archery-mcp-server tools list
MCP_ARCHERY_PASSWORD='provided-at-runtime' ./bin/archery-mcp-server --config config.example.yaml tools list

• Subcommand CLI: mcp starts the server; tools / version / completion are separate commands
• Multi-transport: stdio, Streamable HTTP, and SSE
• Tool filtering: --enabled-tools, --disabled-tools, --enable-domains, --disable-domains
• Engineering defaults: Makefile, Dockerfile, GitHub Actions CI, golangci-lint config, MIT license

./bin/archery-mcp-server tools list
./bin/archery-mcp-server tools list --json
./bin/archery-mcp-server --config config.example.yaml tools describe workflows.sql_check

./bin/archery-mcp-server mcp

Cursor / Claude Desktop style config:

{
  "mcpServers": {
    "archery-mcp-server": {
      "command": "/absolute/path/to/bin/archery-mcp-server",
      "args": ["mcp"]
    }
  }
}

./bin/archery-mcp-server mcp --port 8080
curl -s http://127.0.0.1:8080/healthz

Client config example:

{
  "mcpServers": {
    "archery-mcp-server": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Same process as HTTP mode. Endpoints:

./bin/archery-mcp-server mcp --port 8080 --sse-base-url http://127.0.0.1:8080

# Build
make docker

# Stdio (default ENTRYPOINT is `archery-mcp-server mcp`)
docker run -i --rm archery-mcp-server:dev

# HTTP
docker run --rm -p 8080:8080 archery-mcp-server:dev --port 8080 --listen 0.0.0.0

HTTP / SSE have no auth and no TLS. Default --listen 127.0.0.1. Use only on trusted networks; put a reverse proxy in front if you expose the port.

Priority: flags > environment variables > config file > defaults.

See config.example.yaml:

port: 0
listen: 127.0.0.1
sse_base_url: ""
log_level: info
enabled_tools: []
disabled_tools: []
enabled_domains: []
disabled_domains: []
archery:
  base_url: https://archery.example.com/prefix
  username: mcp-service
  password_env: MCP_ARCHERY_PASSWORD
  request_timeout: 15s

./bin/archery-mcp-server mcp --config config.example.yaml --port 8080

cmd/mcp-server/          # binary entrypoint
internal/cmd/             # cobra CLI (mcp / tools / version / completion)
pkg/core/                 # config / logging / version
pkg/server/mcp/           # MCP registration and transports
pkg/server/http/          # HTTP / SSE / healthz
pkg/toolset/              # Toolset interface and filters
pkg/toolset/archery/      # fixed Archery tool surface
.github/workflows/        # CI

1. Add pkg/toolset/<your-domain>/ implementing toolset.Toolset.
2. Register it in internal/cmd/root.go via defaultToolsets().
3. Control exposure with --enabled-tools / --enable-domains.

make tidy
make format
make lint
make test
make coverage
make ci
make build
make docker

CI (.github/workflows/build.yaml) runs lint, race tests with coverage upload, multi-OS build, CLI smoke (version / tools list), and Docker image build.

third-party-projects/ can hold local reference checkouts. It is listed in .gitignore and is not part of the template deliverable.

MIT