mcp-catalog -example

This MCP server is a Go-based template designed to be driven by AI agents through spec-driven onboarding. It ships with a catalog-centric design that can be configured via mcp-spec.json to expose a dynamic set of items, tools, resources, and prompts. By default, you can list catalog items, fetch item details, and work with a plan/recommendation prompt to tailor recommendations to budget or goals. The server supports running in stdio or HTTP transport, and can be started with or without a spec file. When you provide a spec, the server reads it at startup and configures its behavior accordingly, while keeping the core transports and protocol stable. To explore the included capabilities, you can run the server and use the default tools (listItems, getItemDetails), the catalog resource, and the provided prompts (planRecommendation, itemBrief). The repository also includes demos that show ready-to-run mcp-spec.json files for different use cases such as service catalog, knowledge front door, and Playbook recommender.

Prerequisites:

• Go (1.18+ recommended)
• Git
• Optional: Docker if you want containerized runs

Steps:

1. Install Go from https://golang.org/dl/ and ensure go version is available in your PATH.
2. Clone or download this repository.
3. Build the MCP server:

   go build -o mcp-template-server ./cmd/mcpserver
   

4. Run the server locally (default stdio transport):

   ./mcp-template-server
   

5. Run the server with HTTP transport on port 8080 and a spec file:

   ./mcp-template-server -transport http -port 8080 -spec ./mcp-spec.example.json
   

6. If you want to use the prebuilt demos, point the spec flag to one of the demo specs, for example:

   ./mcp-template-server -transport http -port 8080 -spec demos/service-catalog/mcp-spec.json
   

Docker (optional):

• Build and run a container for reproducible environments:

  docker build -t mcp-template-server:local .
  docker run --rm -p 8080:8080 mcp-template-server:local ./mcp-template-server --transport http --port 8080 --spec /root/mcp-spec.example.json
  

Tips and caveats:

• The server is designed to be spec-driven; unknown JSON fields are rejected at load time, so keep your mcp-spec.json aligned with the schema described in the repo.
• For production, Docker is recommended to achieve isolation and reproducibility (use --read-only and security options as described in the Security Recommendation).
• If you modify the spec, you can validate startup by noting that startup will fail with a validation error if the spec is invalid.
• The default tools/resources/prompts can be overridden by the spec, so consult your mcp-spec.json to see which names and inputs are in use (e.g., list_items, get_item_details, catalog_items, plan_recommendation, item_brief).
• The included demos under demos/ provide ready-to-run examples and schemas to help bootstrap your own MCP server customization.