中文文档

Cloneable minimal MCP (Model Context Protocol) server skeleton with a dual-mode binary: MCP server for AI assistants and a small CLI for humans. Ships with example tools echo / ping.

After creating a repository from this template, initialize its explicit placeholders before building:

./scripts/init-template.sh \
  --module github.com/acme/my-mcp \
  --binary my-mcp \
  --npm-package @acme/my-mcp \
  --image ghcr.io/acme/my-mcp

This creates the build workflow. Add --with-release only when the project is ready to publish; it also creates npm and Docker tag-release workflows. Add --use-ghcr with a ghcr.io/... image to publish to GitHub Container Registry using GITHUB_TOKEN, without Docker registry secrets. Other registries continue to require their credentials. Configure the npm registry before enabling a release. Use --dry-run to inspect the planned initialization without changing files.

# Requires Go 1.25+ (see .tool-versions)
make build
./bin/mcp-template-binary-placeholder version

# Start MCP server (stdio, default)
./bin/mcp-template-binary-placeholder mcp

# List / call tools from the CLI (no MCP client required)
./bin/mcp-template-binary-placeholder tools list
./bin/mcp-template-binary-placeholder tools call echo --params '{"message":"hello"}'
./bin/mcp-template-binary-placeholder tools call ping --params '{}'

• 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/mcp-template-binary-placeholder tools list
./bin/mcp-template-binary-placeholder tools list --json
./bin/mcp-template-binary-placeholder tools describe echo
./bin/mcp-template-binary-placeholder tools describe echo --json
./bin/mcp-template-binary-placeholder tools call echo --params '{"message":"hello"}'
echo '{"message":"hello"}' | ./bin/mcp-template-binary-placeholder tools call echo --params-file -
./bin/mcp-template-binary-placeholder tools call ping --params '{}'

./bin/mcp-template-binary-placeholder mcp

Cursor / Claude Desktop style config:

{
  "mcpServers": {
    "mcp-template-binary-placeholder": {
      "command": "/absolute/path/to/bin/mcp-template-binary-placeholder",
      "args": ["mcp"]
    }
  }
}

./bin/mcp-template-binary-placeholder mcp --port 8080
curl -s http://127.0.0.1:8080/healthz

Client config example:

{
  "mcpServers": {
    "mcp-template-binary-placeholder": {
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Same process as HTTP mode. Endpoints:

./bin/mcp-template-binary-placeholder mcp --port 8080 --sse-base-url http://127.0.0.1:8080

# Build
make docker

# Stdio (default ENTRYPOINT is `mcp-template-binary-placeholder mcp`)
docker run -i --rm mcp-template-image-placeholder:dev

# HTTP
docker run --rm -p 8080:8080 mcp-template-image-placeholder: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: []

./bin/mcp-template-binary-placeholder 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/example/      # sample tools (replace with your domain)
.github/workflows/        # CI
scripts/init-template.sh  # derived-project initializer
templates/                # CI and release scaffolding copied by the initializer

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

Generated build CI (.github/workflows/build.yaml) runs lint, tests, a multi-OS build with CLI smoke checks, and a 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