# ondc-official/automation-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ondc-official/automation-mcp
- Repository: https://github.com/ondc-official/automation-mcp

## Overview

ondc-mcp is a stateless MCP server that acts as a mock ONDC participant. The main workflow is: an MCP client selects a build and creates a session, then drives a flow while a real participant sends signed network callbacks; the server records exchanges and returns outcomes. Separate browser forms and a session viewer support manual testing, while catalog, protocol knowledge, validation, feedback, and monitoring provide supporting capabilities. The README documents the tool→service→repository layering; sampled excerpts confirm selected session, flow, HTTP, and viewer wiring, but not every module’s internal calls.

Main entry points: [`src/mcp/capabilities.ts`](https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/capabilities.ts) (Capability registry), [`src/app.ts`](https://github.com/ondc-official/automation-mcp/blob/main/src/app.ts) (Fastify app), [`src/modules/flow/flow.service.ts`](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/flow.service.ts) (Flow service), [`src/mcp/server.ts`](https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/server.ts) (MCP server factory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_stdio["stdio entrypoint<br/>[stdio.ts]"]
  node_http_entry["HTTP entrypoint<br/>[http.ts]"]
  node_http_app["Fastify app<br/>[app.ts]"]
  node_mcp_server["MCP server factory<br/>[server.ts]"]
  node_capabilities["Capability registry<br/>[capabilities.ts]"]
  node_container["Shared container<br/>[container.ts]"]
end

subgraph group_domain["Test workflow"]
  node_catalog["Build and flow catalog<br/>[catalog.tool.ts]"]
  node_session["Session management<br/>[session.tool.ts]"]
  node_session_service["Session service<br/>[session.service.ts]"]
  node_flow["Flow execution<br/>[flow.tool.ts]"]
  node_flow_service["Flow service<br/>[flow.service.ts]"]
  node_flow_engine["Flow state engine<br/>[to-engine-flow.ts]"]
  node_records["Exchange records<br/>[record.tool.ts]"]
end

subgraph group_network["Participant surfaces"]
  node_receiver["Inbound receiver<br/>[receiver.routes.ts]"]
  node_sender["Signed sender<br/>[sender.service.ts]"]
  node_forms["Hosted forms<br/>[forms.routes.ts]"]
end

subgraph group_knowledge["Protocol capabilities"]
  node_protocol["Protocol knowledge<br/>[protocol.tool.ts]"]
  node_validation["Payload validation<br/>[validate.tool.ts]"]
  node_feedback["Run feedback<br/>[feedback.tool.ts]"]
end

subgraph group_operations["Operations"]
  node_health["Health probes<br/>[health.routes.ts]"]
  node_metrics["Prometheus metrics<br/>[metrics.routes.ts]"]
  node_viewer["Session viewer<br/>[ui.routes.ts]"]
  node_cache[("Cache store<br/>[cache-store.ts]")]
end

node_mcp_client(("MCP client"))
node_participant(("ONDC participant"))
node_operator(("Operator / tester"))

node_mcp_client -->|"uses stdio"| node_stdio
node_mcp_client -->|"uses HTTP"| node_http_entry
node_stdio -->|"builds server"| node_mcp_server
node_http_entry -->|"starts app"| node_http_app
node_http_app -->|"serves MCP"| node_mcp_server
node_mcp_server -->|"registers tools"| node_capabilities
node_capabilities -->|"registers"| node_catalog
node_capabilities -->|"registers"| node_session
node_capabilities -->|"registers"| node_flow
node_capabilities -->|"registers"| node_records
node_capabilities -->|"registers"| node_protocol
node_capabilities -->|"registers"| node_validation
node_capabilities -->|"registers"| node_feedback
node_session -->|"calls"| node_session_service
node_session_service -->|"lists flows"| node_catalog
node_flow -->|"calls"| node_flow_service
node_flow_service -->|"builds engine flow"| node_flow_engine
node_participant -->|"posts callbacks"| node_receiver
node_receiver -->|"handles inbound"| node_flow_service
node_flow_service -->|"sends requests"| node_sender
node_participant -->|"opens or submits"| node_forms
node_operator -->|"views sessions"| node_viewer
node_http_app -->|"registers routes"| node_receiver
node_http_app -->|"registers routes"| node_forms
node_http_app -->|"registers routes"| node_health
node_http_app -->|"registers routes"| node_metrics
node_http_app -->|"registers routes"| node_viewer
node_viewer -->|"reads records"| node_cache
node_container -->|"provides store"| node_cache

click node_stdio "https://github.com/ondc-official/automation-mcp/blob/main/src/entrypoints/stdio.ts"
click node_http_entry "https://github.com/ondc-official/automation-mcp/blob/main/src/entrypoints/http.ts"
click node_http_app "https://github.com/ondc-official/automation-mcp/blob/main/src/app.ts"
click node_mcp_server "https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/server.ts"
click node_capabilities "https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/capabilities.ts"
click node_container "https://github.com/ondc-official/automation-mcp/blob/main/src/container.ts"
click node_catalog "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/catalog/catalog.tool.ts"
click node_session "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/session/session.tool.ts"
click node_session_service "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/session/session.service.ts"
click node_flow "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/flow.tool.ts"
click node_flow_service "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/flow.service.ts"
click node_flow_engine "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/engine/to-engine-flow.ts"
click node_records "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/record/record.tool.ts"
click node_receiver "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/transport/receiver.routes.ts"
click node_sender "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/transport/sender.service.ts"
click node_forms "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/forms/forms.routes.ts"
click node_protocol "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/protocol/protocol.tool.ts"
click node_validation "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/validate/validate.tool.ts"
click node_feedback "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/feedback/feedback.tool.ts"
click node_health "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/health/health.routes.ts"
click node_metrics "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/metrics/metrics.routes.ts"
click node_viewer "https://github.com/ondc-official/automation-mcp/blob/main/src/modules/ui/ui.routes.ts"
click node_cache "https://github.com/ondc-official/automation-mcp/blob/main/src/lib/cache/cache-store.ts"

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_stdio,node_http_entry,node_http_app,node_mcp_server,node_capabilities,node_container,node_mcp_client toneBlue
class node_catalog,node_session,node_session_service,node_flow,node_flow_service,node_flow_engine,node_records toneAmber
class node_receiver,node_sender,node_forms toneMint
class node_protocol,node_validation,node_feedback toneRose
class node_health,node_metrics,node_viewer,node_cache,node_participant,node_operator toneIndigo
```

## Components

### Server runtime

- [stdio entrypoint](https://github.com/ondc-official/automation-mcp/blob/main/src/entrypoints/stdio.ts): `src/entrypoints/stdio.ts`
- [HTTP entrypoint](https://github.com/ondc-official/automation-mcp/blob/main/src/entrypoints/http.ts): `src/entrypoints/http.ts`
- [Fastify app](https://github.com/ondc-official/automation-mcp/blob/main/src/app.ts): `src/app.ts`
- [MCP server factory](https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Capability registry](https://github.com/ondc-official/automation-mcp/blob/main/src/mcp/capabilities.ts): `src/mcp/capabilities.ts`
- [Shared container](https://github.com/ondc-official/automation-mcp/blob/main/src/container.ts): `src/container.ts`

### Test workflow

- [Build and flow catalog](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/catalog/catalog.tool.ts): `src/modules/catalog/catalog.tool.ts`
- [Session management](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/session/session.tool.ts): `src/modules/session/session.tool.ts`
- [Session service](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/session/session.service.ts): `src/modules/session/session.service.ts`
- [Flow execution](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/flow.tool.ts): `src/modules/flow/flow.tool.ts`
- [Flow service](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/flow.service.ts): `src/modules/flow/flow.service.ts`
- [Flow state engine](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/flow/engine/to-engine-flow.ts): `src/modules/flow/engine/to-engine-flow.ts`
- [Exchange records](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/record/record.tool.ts): `src/modules/record/record.tool.ts`

### Participant surfaces

- [Inbound receiver](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/transport/receiver.routes.ts): `src/modules/transport/receiver.routes.ts`
- [Signed sender](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/transport/sender.service.ts): `src/modules/transport/sender.service.ts`
- [Hosted forms](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/forms/forms.routes.ts): `src/modules/forms/forms.routes.ts`

### Protocol capabilities

- [Protocol knowledge](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/protocol/protocol.tool.ts): `src/modules/protocol/protocol.tool.ts`
- [Payload validation](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/validate/validate.tool.ts): `src/modules/validate/validate.tool.ts`
- [Run feedback](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/feedback/feedback.tool.ts): `src/modules/feedback/feedback.tool.ts`

### Operations

- [Health probes](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/health/health.routes.ts): `src/modules/health/health.routes.ts`
- [Prometheus metrics](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/metrics/metrics.routes.ts): `src/modules/metrics/metrics.routes.ts`
- [Session viewer](https://github.com/ondc-official/automation-mcp/blob/main/src/modules/ui/ui.routes.ts): `src/modules/ui/ui.routes.ts`
- [Cache store](https://github.com/ondc-official/automation-mcp/blob/main/src/lib/cache/cache-store.ts): `src/lib/cache/cache-store.ts`

### Other components

- **MCP client**
- **ONDC participant**
- **Operator / tester**

## Connections

- MCP client → stdio entrypoint: uses stdio
- MCP client → HTTP entrypoint: uses HTTP
- stdio entrypoint → MCP server factory: builds server
- HTTP entrypoint → Fastify app: starts app
- Fastify app → MCP server factory: serves MCP
- MCP server factory → Capability registry: registers tools
- Capability registry → Build and flow catalog: registers
- Capability registry → Session management: registers
- Capability registry → Flow execution: registers
- Capability registry → Exchange records: registers
- Capability registry → Protocol knowledge: registers
- Capability registry → Payload validation: registers
- Capability registry → Run feedback: registers
- Session management → Session service: calls
- Session service → Build and flow catalog: lists flows
- Flow execution → Flow service: calls
- Flow service → Flow state engine: builds engine flow
- ONDC participant → Inbound receiver: posts callbacks
- Inbound receiver → Flow service: handles inbound
- Flow service → Signed sender: sends requests
- ONDC participant → Hosted forms: opens or submits
- Operator / tester → Session viewer: views sessions
- Fastify app → Inbound receiver: registers routes
- Fastify app → Hosted forms: registers routes
- Fastify app → Health probes: registers routes
- Fastify app → Prometheus metrics: registers routes
- Fastify app → Session viewer: registers routes
- Session viewer → Cache store: reads records
- Shared container → Cache store: provides store