go -example

This Go-based MCP server template is designed to be driven by an AI agent through specification files. It can operate in stdio (default) or HTTP transport and is configured at startup via a mcp-spec.json file. The server exposes a stable MCP core and transport layer while the domain behavior is defined by the spec, enabling rapid iteration for onboarding catalogs, playbooks, or knowledge front-doors. When run with a spec, the server loads the spec, validates required sections (tools, resources, prompts, and items), and exposes the configured capabilities accordingly. You can explore demo specs under demos/ to see concrete examples of a service catalog, playbook recommender, knowledge front door, incident runbook template, and edge-secure deployment.

To start the server locally, build the binary and run it. You can run without a spec for default in-code catalog behavior or provide a -spec path to drive behavior from the spec. The server supports multiple transports (e.g., stdio by default or HTTP when started with -transport http and -port N). Tools exposed by default include list_items (to enumerate lookup values) and get_item_details (to fetch item details by a lookup field), while resources expose catalog_items as the full catalog dataset. Prompts such as plan_recommendation and item_brief can be driven by the spec for tailored recommendations and item briefs.

Prerequisites:

• Go 1.17+ (or newer) installed on your system
• Git to clone the repository (optional if you already have the code)
• Basic Go tooling available in your PATH

Step-by-step installation:

1. Clone the repository (or navigate to it if you already have it): git clone <repository-url> cd <repository-directory>

2. Ensure Go is installed by checking the version: go version

3. Build the MCP server binary: go build -o mcp-template-server ./cmd/mcpserver

4. Run the server (no spec): ./mcp-template-server

5. Run the server with a spec file (spec-driven behavior): ./mcp-template-server -spec ./mcp-spec.example.json

6. Optional: run the HTTP transport variant on a specified port: ./mcp-template-server -transport http -port 8080 -spec ./mcp-spec.example.json

Tips and common considerations:

• If you are deploying in production or shared environments, consider using Docker to isolate the runtime as recommended in the Security section of the README.
• The server validates the spec at startup; invalid specs will fail startup with a validation error.
• Demo specs under demos/ provide ready-to-run examples for various use cases. You can iterate by editing or replacing the mcp-spec.json with your own spec.
• When using -spec, the detail lookup field is driven by the spec (get_item_details.inputSchema.required[0]); ensure your spec adheres to the validation rules described in the Spec Schema section.
• For debugging, run tests with: go test ./... and/or build with verbose output to inspect startup validation messages.
• If you need to run multiple instances or scale, consider containerizing the server and using the provided Docker deployment instructions in the README.