# kocierik/mcp-nomad architecture

> Architecture diagram of the GitHub repository kocierik/mcp-nomad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kocierik/mcp-nomad
- Repository: https://github.com/kocierik/mcp-nomad

## Overview

MCP Nomad is a Go server that exposes Nomad operations as MCP tools and resources over stdio, SSE, or Streamable HTTP. The main workflow is an MCP client request entering the server, being dispatched to a domain tool handler, then using typed Nomad API helpers to call the Nomad HTTP API and return a formatted result. Tools cover jobs, ACLs, allocations, deployments, namespaces, nodes, logs, variables, volumes, cluster operations, and Sentinel policies; resources and prompts provide additional MCP capabilities. The source excerpts show selected registrations and calls; other domain links are documented in the README or remain unverified.

Main entry points: [`utils`](https://github.com/kocierik/mcp-nomad/tree/main/utils) (Other API Helpers), [`main.go`](https://github.com/kocierik/mcp-nomad/blob/main/main.go) (Server & Transport), [`utils/client_jobs.go`](https://github.com/kocierik/mcp-nomad/blob/main/utils/client_jobs.go) (Job API Helpers), [`tools/jobs.go`](https://github.com/kocierik/mcp-nomad/blob/main/tools/jobs.go) (Job Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_server_entry["Server &amp; Transport<br/>[main.go]"]
end

subgraph group_tools["Nomad Tools"]
  node_job_tools["Job Operations<br/>[jobs.go]"]
  node_acl_tools["ACL Operations<br/>[acl.go]"]
  node_allocation_tools["Allocation Operations<br/>[allocations.go]"]
  node_deployment_tools["Deployment Operations<br/>[deployments.go]"]
  node_namespace_tools["Namespace Operations<br/>[namespaces.go]"]
  node_node_tools["Node Operations<br/>[nodes.go]"]
  node_log_tools["Log Operations<br/>[logs.go]"]
  node_variable_tools["Variable Operations<br/>[variables.go]"]
  node_volume_tools["Volume Operations<br/>[volumes.go]"]
  node_cluster_tools["Cluster Operations<br/>[cluster.go]"]
  node_sentinel_tools["Sentinel Policies<br/>[sentinel.go]"]
end

subgraph group_api["Nomad API Client"]
  node_nomad_client["Nomad Client<br/>[client.go]"]
  node_job_api["Job API Helpers<br/>[client_jobs.go]"]
  node_acl_api["ACL API Helpers<br/>[client_acl.go]"]
  node_variable_api["Variable API Helpers"]
  node_node_api["Node API Helpers<br/>[client_nodes.go]"]
  node_other_api["Other API Helpers"]
end

subgraph group_capabilities["MCP Capabilities"]
  node_resource_handlers["Resources<br/>[resources.go]"]
  node_prompt_handlers["Prompts<br/>[prompts.go]"]
end

node_mcp_client(("MCP Client"))
node_nomad["Nomad HTTP API"]

node_mcp_client -->|"sends requests"| node_server_entry
node_server_entry -->|"registers tools"| node_job_tools
node_server_entry -->|"registers tools"| node_acl_tools
node_server_entry -.->|"registers resources"| node_resource_handlers
node_server_entry -->|"registers prompts"| node_prompt_handlers
node_job_tools -->|"calls"| node_job_api
node_acl_tools -->|"calls"| node_acl_api
node_variable_tools -->|"calls"| node_variable_api
node_resource_handlers -->|"reads job details"| node_job_api
node_nomad_client -.->|"sends HTTP requests"| node_nomad
node_job_api -.->|"calls API"| node_nomad
node_acl_api -.->|"calls API"| node_nomad
node_variable_api -.->|"calls API"| node_nomad
node_node_api -.->|"calls API"| node_nomad
node_allocation_tools -.->|"calls"| node_other_api
node_deployment_tools -.->|"calls"| node_other_api
node_namespace_tools -.->|"calls"| node_other_api
node_node_tools -.->|"calls"| node_node_api
node_log_tools -.->|"calls"| node_other_api
node_volume_tools -.->|"calls"| node_other_api
node_cluster_tools -.->|"calls"| node_other_api
node_sentinel_tools -.->|"calls"| node_other_api
node_prompt_handlers -.->|"uses APIs"| node_other_api

click node_server_entry "https://github.com/kocierik/mcp-nomad/blob/main/main.go"
click node_job_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/jobs.go"
click node_acl_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/acl.go"
click node_allocation_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/allocations.go"
click node_deployment_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/deployments.go"
click node_namespace_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/namespaces.go"
click node_node_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/nodes.go"
click node_log_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/logs.go"
click node_variable_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/variables.go"
click node_volume_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/volumes.go"
click node_cluster_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/cluster.go"
click node_sentinel_tools "https://github.com/kocierik/mcp-nomad/blob/main/tools/sentinel.go"
click node_resource_handlers "https://github.com/kocierik/mcp-nomad/blob/main/tools/resources.go"
click node_prompt_handlers "https://github.com/kocierik/mcp-nomad/blob/main/prompts/prompts.go"
click node_nomad_client "https://github.com/kocierik/mcp-nomad/blob/main/utils/client.go"
click node_job_api "https://github.com/kocierik/mcp-nomad/blob/main/utils/client_jobs.go"
click node_acl_api "https://github.com/kocierik/mcp-nomad/blob/main/utils/client_acl.go"
click node_variable_api "https://github.com/kocierik/mcp-nomad/blob/main/utils/client_variables.go"
click node_node_api "https://github.com/kocierik/mcp-nomad/blob/main/utils/client_nodes.go"
click node_other_api "https://github.com/kocierik/mcp-nomad/tree/main/utils"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_entry,node_mcp_client toneBlue
class node_job_tools,node_acl_tools,node_allocation_tools,node_deployment_tools,node_namespace_tools,node_node_tools,node_log_tools,node_variable_tools,node_volume_tools,node_cluster_tools,node_sentinel_tools toneAmber
class node_nomad_client,node_job_api,node_acl_api,node_variable_api,node_node_api,node_other_api,node_nomad toneMint
class node_resource_handlers,node_prompt_handlers toneRose
```

## Components

### MCP Server

- [Server & Transport](https://github.com/kocierik/mcp-nomad/blob/main/main.go): `main.go`

### Nomad Tools

- [Job Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/jobs.go): `tools/jobs.go`
- [ACL Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/acl.go): `tools/acl.go`
- [Allocation Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/allocations.go): `tools/allocations.go`
- [Deployment Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/deployments.go): `tools/deployments.go`
- [Namespace Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/namespaces.go): `tools/namespaces.go`
- [Node Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/nodes.go): `tools/nodes.go`
- [Log Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/logs.go): `tools/logs.go`
- [Variable Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/variables.go): `tools/variables.go`
- [Volume Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/volumes.go): `tools/volumes.go`
- [Cluster Operations](https://github.com/kocierik/mcp-nomad/blob/main/tools/cluster.go): `tools/cluster.go`
- [Sentinel Policies](https://github.com/kocierik/mcp-nomad/blob/main/tools/sentinel.go): `tools/sentinel.go`

### Nomad API Client

- [Nomad Client](https://github.com/kocierik/mcp-nomad/blob/main/utils/client.go): `utils/client.go`
- [Job API Helpers](https://github.com/kocierik/mcp-nomad/blob/main/utils/client_jobs.go): `utils/client_jobs.go`
- [ACL API Helpers](https://github.com/kocierik/mcp-nomad/blob/main/utils/client_acl.go): `utils/client_acl.go`
- [Variable API Helpers](https://github.com/kocierik/mcp-nomad/blob/main/utils/client_variables.go): `utils/client_variables.go`
- [Node API Helpers](https://github.com/kocierik/mcp-nomad/blob/main/utils/client_nodes.go): `utils/client_nodes.go`
- [Other API Helpers](https://github.com/kocierik/mcp-nomad/tree/main/utils): `utils`

### MCP Capabilities

- [Resources](https://github.com/kocierik/mcp-nomad/blob/main/tools/resources.go): `tools/resources.go`
- [Prompts](https://github.com/kocierik/mcp-nomad/blob/main/prompts/prompts.go): `prompts/prompts.go`

### Other components

- **MCP Client**
- **Nomad HTTP API**

## Connections

- MCP Client → Server & Transport: sends requests (evidence: `README.md`)
- Server & Transport → Job Operations: registers tools (evidence: `main.go`)
- Server & Transport → ACL Operations: registers tools (evidence: `main.go`)
- Server & Transport → Resources: registers resources
- Server & Transport → Prompts: registers prompts (evidence: `main.go`)
- Job Operations → Job API Helpers: calls (evidence: `tools/jobs.go`)
- ACL Operations → ACL API Helpers: calls (evidence: `tools/acl.go`)
- Variable Operations → Variable API Helpers: calls (evidence: `tools/variables.go`)
- Resources → Job API Helpers: reads job details (evidence: `tools/resources.go`)
- Nomad Client → Nomad HTTP API: sends HTTP requests
- Job API Helpers → Nomad HTTP API: calls API
- ACL API Helpers → Nomad HTTP API: calls API
- Variable API Helpers → Nomad HTTP API: calls API
- Node API Helpers → Nomad HTTP API: calls API
- Allocation Operations → Other API Helpers: calls (evidence: `tools/allocations.go`)
- Deployment Operations → Other API Helpers: calls (evidence: `tools/deployments.go`)
- Namespace Operations → Other API Helpers: calls (evidence: `tools/namespaces.go`)
- Node Operations → Node API Helpers: calls
- Log Operations → Other API Helpers: calls (evidence: `tools/logs.go`)
- Volume Operations → Other API Helpers: calls (evidence: `tools/volumes.go`)
- Cluster Operations → Other API Helpers: calls (evidence: `tools/cluster.go`)
- Sentinel Policies → Other API Helpers: calls (evidence: `tools/sentinel.go`)
- Prompts → Other API Helpers: uses APIs
