mcp-catalog -template

This MCP server is a Go-based template designed to be driven by an AI agent through spec-driven configuration. It loads a world of behavior from an mcp-spec.json file, enabling a stable transport and core MCP protocol while letting domain-specific content and capabilities be defined in the spec. By default, the server exposes a catalog-like set of resources and prompts, with tools such as list_items and get_item_details to query dynamic items, and prompts like plan_recommendation and item_brief to generate concise outputs. Run with a spec to tailor the catalog, items, and recommended actions to your domain (e.g., service catalog, knowledge front door, or incident runbooks).

To use locally, start the server and interact via the configured HTTP endpoint. When started with a spec, the server validates and loads the spec, then serves the configured capabilities over MCP. You can also explore the included demo specs under demos/ to see example configurations and item data. If you want reproducible deployment, consider Docker-based runs described in the documentation; the container can enforce isolation and consistent startup parameters.

Prerequisites:

• Go toolchain installed (go 1.20+ recommended)
• Optional: Docker for containerized deployment

Install and run locally (no Docker):

1. Install Go if not already installed.
2. Build the MCP template server: go build -o mcp-template-server ./cmd/mcpserver
3. Run the server with defaults (stdio): ./mcp-template-server
4. Run with HTTP transport on port 8080 (spec can be provided as well): ./mcp-template-server -transport http -port 8080
5. If you have a spec file, start with the spec path: ./mcp-template-server -spec ./mcp-spec.example.json

Using Docker (recommended for production):

1. Build the image: docker build -t mcp-template-server:local .
2. Run the container (HTTP on port 8080 by default): docker run --rm -p 8080:8080 mcp-template-server:local
3. Run with a spec inside the container: docker run --rm -p 8080:8080
   -v "$(pwd)/mcp-spec.example.json:/root/mcp-spec.example.json:ro"
   mcp-template-server:local
   ./mcp-template-server --transport http --port 8080 --spec /root/mcp-spec.example.json

Tips and notes:

• This server is contract-first: transports and MCP dispatch remain stable while domain behavior is configured via mcp-spec.json. Unknown JSON fields in the spec are rejected at load time.
• For production or shared environments, Docker is recommended to improve isolation and reproducibility. You can leverage runtime restrictions and security options in containers.
• The server exposes endpoints like POST /mcp, GET /mcp, DELETE /mcp, and GET /health. Use the demo specs under demos/ to validate behavior before plugging in your own data.
• When using a spec, ensure the required tools, resources, and prompts match the schema (list_items, get_item_details, catalog_items, plan_recommendation, item_brief) and that the item lookup field is a unique, non-empty string.
• If you’re testing locally, you can perform a quick smoke test by loading a demo spec and issuing a short startup to confirm the HTTP endpoint responds correctly.