For developers

kartoza-mcp is a small, opinionated Go server. The fastest path to productive work is:

1. nix develop — drops you in a shell with the exact toolchain.
2. nix run .#test — green tests on the first run.
3. Add a tool — copy clusterHandler, register it from main.

• Architecture

  ---

  How the MCP server, Quadtree, DBSCAN and Orb fit together. Sequence diagrams included.

  Architecture

• Add a new tool

  ---

  Step-by-step recipe for adding a new spatial analytic: buffer, hull, voronoi, isochrone — whatever your workflow needs.

  Add a tool

• Coding standards

  ---

  REUSE headers, Kartoza credit, gofmt, errcheck. The non-negotiables.

  Standards

• Testing

  ---

  Table-driven Go tests + golden-file JSON fixtures. How to write them, how to run them.

  Testing

• :material-folder-tree:{ .lg .middle } Project structure

  ---

  Where things live and why.

  Project structure

• Contributing

  ---

  Branching, PR template, review expectations, release cadence.

  Contributing

The five-minute mental model

flowchart TB
    subgraph stdio["stdio"]
      C[MCP Client]
    end
    subgraph srv["kartoza-mcp (Go process)"]
      M[main.go<br/>server.NewMCPServer]
      H1[clusterHandler]
      H2[your new handler]
      Q[Quadtree / Orb]
    end
    C <-->|JSON-RPC over stdio| M
    M --> H1
    M --> H2
    H1 --> Q
    H2 --> Q

One Go file (main.go) wires up the MCP server. Each tool is a Go function with the signature func(ctx, mcp.CallToolRequest) (*mcp.CallToolResult, error). That's the whole conceptual surface.

Why so little structure?

Spatial-analysis tools tend to be small, mostly-stateless functions over geometry. We keep the codebase flat on purpose. When a handler outgrows main.go, lift it into its own pkg/<tool> directory — there's no rush.