This MCP server demonstrates a modular recommendation service built with Go-Kratos and the MCP framework. It wires together recall, ranking, and filtering modules as separate components that communicate through MCP contracts, enabling independent development and deployment while preserving a unified request flow. The service exposes both MCP interfaces for cross-service coordination and an HTTP surface for direct integration or testing. To use it, start the server (via the provided Make scripts or your container runtime) and interact with the MCP tools registered at startup. The MCP protocol drives the call flow: a client submits a request, the MCP runtime parses it into a contextual CallContext, the recall module generates candidate items, the rank module orders them, and the filter module applies business rules before returning the final result. Expect observability features such as tracing, logging, and metrics, as well as compatibility considerations for Protobuf JSON encoding (notably int64 values may appear as strings in JSON payloads).

Prerequisites:

• Docker (for containerized run) or Go toolchain if you prefer local build
• Make (optional, for convenience)
• Protobuf tooling if you intend to generate stubs

1. Clone the repository: git clone https://github.com/tx7do/go-kratos-mcp-demo.git cd go-kratos-mcp-demo

2. Install dependencies (Go modules): go mod download

3. Generate code and wire dependencies (if you use the provided Make targets): make api openapi # generate API definitions make wire # set up dependency injection

4. Run the service (Docker-based example or local binary):

   Docker container (recommended for MCP demos)

   docker compose up -d || docker run -d --name mcp-demo -p 8080:8080 tx7do/go-kratos-mcp-demo:latest

   Local binary (if you prefer to build and run directly)

   go build -o mcp-demo ./... ./mcp-demo

5. Test locally using an MCP client or the HTTP interface exposed by the service. Ensure the runtime environment is configured to handle Protobuf/JSON compatibility for int64 fields.

Prerequisites recap: ensure Docker or a Go toolchain is installed, the repository is checked out, and you have network access to fetch dependencies and, if using Docker, a compatible container image name.

Tips and common issues:

• Protobuf JSON encoding: int64 values may be serialized as strings in JSON. Ensure test assertions account for both numeric and string representations.
• Module boundaries: recall, rank, and filter are implemented as separate modules behind interfaces; you can swap implementations without changing the MCP contract.
• Observability: enable tracing, logging, and metrics as per Kratos and MCP integration guidelines to diagnose cross-module flows.
• Environment variables: adjust KRATOS_ENV, MCP_LOG_LEVEL, and MCP_CONFIG_PATH to fit your deployment environment. If running via Docker, make sure volume mounts or config paths are accessible inside the container.
• Compatibility: MCP protocol support is demonstrated via standard Protobuf contracts; ensure clients generated in other languages adhere to the same version of the contract.