# vimarsh244/tally-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/vimarsh244/tally-mcp-server
- Repository: https://github.com/vimarsh244/tally-mcp-server

## Overview

Tally Prime MCP Server exposes Tally ERP data and operations to MCP clients. A client connects through local stdio or the HTTP transport; the server registers read and optional write tools, which query or update Tally through its XML interface. Reporting results can be cached for later SQL queries. The HTTP deployment additionally supports OAuth, per-profile realms and an administration API. The map follows documented capabilities and indexed imports; unsampled module internals are represented only where their role is documented.

Main entry points: [`src/tools/index.mts`](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/index.mts) (Tool registry), [`src/tally/index.mts`](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/index.mts) (Tally operations), [`src/http/app.mts`](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/app.mts) (HTTP app), [`src/tally/client.mts`](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/client.mts) (XML transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_transport["Entry and HTTP"]
  node_entry["Server entry<br/>[index.mts]"]
  node_server["Web server<br/>[server.mts]"]
  node_http_app["HTTP app<br/>[app.mts]"]
  node_http_routes["MCP HTTP route<br/>[mcp-route.mts]"]
  node_oauth["OAuth routes<br/>[oauth.mts]"]
  node_admin["Setup API<br/>[admin.mts]"]
end

subgraph group_tools["MCP tools"]
  node_mcp["MCP server<br/>[mcp.mts]"]
  node_tool_registry["Tool registry<br/>[index.mts]"]
  node_metadata["Metadata tools<br/>[metadata.mts]"]
  node_query["SQL query tools<br/>[query.mts]"]
  node_statements["Statement tools<br/>[statements.mts]"]
  node_ledgers["Ledger tools<br/>[ledgers.mts]"]
  node_inventory["Inventory tools<br/>[inventory.mts]"]
  node_vouchers["Voucher tools<br/>[vouchers.mts]"]
  node_context["Context tools<br/>[context.mts]"]
  node_writes["Master write tools<br/>[write.mts]"]
  node_voucher_writes["Voucher write tools<br/>[voucher-write.mts]"]
  node_shared["Tool helpers<br/>[shared.mts]"]
end

subgraph group_tally["Tally integration"]
  node_tally_api["Tally operations<br/>[index.mts]"]
  node_tally_client["XML transport<br/>[client.mts]"]
  node_templates["XML templates<br/>[templates.mts]"]
  node_definitions["Data definitions<br/>[definition.mts]"]
end

subgraph group_runtime["Runtime state"]
  node_auth_store["Auth store<br/>[store.mts]"]
  node_realm["Realm resolver<br/>[realm.mts]"]
  node_profiles["Profile registry<br/>[profiles.mts]"]
  node_tally_target["Tally target<br/>[tally-target.mts]"]
  node_result_cache[("Result cache<br/>[database.mts]")]
  node_config["Configuration<br/>[config.mts]"]
end

node_client(("MCP client"))
node_tally_service[("Tally Prime")]

node_client -->|"starts local"| node_entry
node_client -->|"connects over HTTP"| node_http_app
node_entry -->|"starts"| node_mcp
node_server -->|"creates"| node_http_app
node_http_app -->|"registers"| node_http_routes
node_http_app -->|"registers"| node_oauth
node_http_app -->|"creates resolver"| node_realm
node_http_app -->|"registers"| node_admin
node_oauth -->|"uses"| node_auth_store
node_http_routes -->|"serves"| node_mcp
node_http_routes -->|"resolves realm"| node_realm
node_realm -->|"looks up"| node_profiles
node_realm -->|"selects target"| node_tally_target
node_admin -->|"manages"| node_profiles
node_admin -->|"checks Tally"| node_tally_api
node_mcp -->|"registers tools"| node_tool_registry
node_tool_registry -->|"registers"| node_metadata
node_tool_registry -->|"registers"| node_query
node_tool_registry -->|"registers"| node_statements
node_tool_registry -->|"registers"| node_ledgers
node_tool_registry -->|"registers"| node_inventory
node_tool_registry -->|"registers"| node_vouchers
node_tool_registry -->|"registers"| node_context
node_tool_registry -->|"registers optionally"| node_writes
node_tool_registry -->|"registers optionally"| node_voucher_writes
node_tool_registry -->|"creates cache"| node_result_cache
node_shared -->|"caches results"| node_result_cache
node_metadata -->|"reads definitions"| node_definitions
node_query -->|"queries Tally"| node_tally_api
node_query -->|"queries cache"| node_result_cache
node_statements -->|"fetches reports"| node_tally_api
node_ledgers -->|"queries Tally"| node_tally_api
node_inventory -->|"queries Tally"| node_tally_api
node_vouchers -->|"queries Tally"| node_tally_api
node_context -->|"queries Tally"| node_tally_api
node_writes -->|"writes masters"| node_tally_api
node_voucher_writes -->|"writes vouchers"| node_tally_api
node_tally_api -->|"uses transport"| node_tally_client
node_tally_client -->|"renders XML"| node_templates
node_tally_client -->|"reads target"| node_tally_target
node_tally_client -->|"posts XML"| node_tally_service
node_tally_api -->|"uses definitions"| node_definitions
node_tool_registry -->|"reads settings"| node_config

click node_entry "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/index.mts"
click node_server "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/server.mts"
click node_http_app "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/app.mts"
click node_http_routes "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/mcp-route.mts"
click node_oauth "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/oauth.mts"
click node_auth_store "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/store.mts"
click node_realm "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/realm.mts"
click node_admin "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/admin.mts"
click node_profiles "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/profiles.mts"
click node_mcp "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/mcp.mts"
click node_tool_registry "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/index.mts"
click node_metadata "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/metadata.mts"
click node_query "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/query.mts"
click node_statements "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/statements.mts"
click node_ledgers "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/ledgers.mts"
click node_inventory "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/inventory.mts"
click node_vouchers "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/vouchers.mts"
click node_context "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/context.mts"
click node_writes "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/write.mts"
click node_voucher_writes "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/voucher-write.mts"
click node_shared "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/shared.mts"
click node_tally_api "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/index.mts"
click node_tally_client "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/client.mts"
click node_templates "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/templates.mts"
click node_definitions "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/definition.mts"
click node_tally_target "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally-target.mts"
click node_result_cache "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/database.mts"
click node_config "https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/config.mts"

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_entry,node_server,node_http_app,node_http_routes,node_oauth,node_admin,node_client toneBlue
class node_mcp,node_tool_registry,node_metadata,node_query,node_statements,node_ledgers,node_inventory,node_vouchers,node_context,node_writes,node_voucher_writes,node_shared,node_tally_service toneAmber
class node_tally_api,node_tally_client,node_templates,node_definitions toneMint
class node_auth_store,node_realm,node_profiles,node_tally_target,node_result_cache,node_config toneRose
```

## Components

### Entry and HTTP

- [Server entry](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/index.mts): `src/index.mts`
- [Web server](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/server.mts): `src/server.mts`
- [HTTP app](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/app.mts): `src/http/app.mts`
- [MCP HTTP route](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/mcp-route.mts): `src/http/mcp-route.mts`
- [OAuth routes](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/oauth.mts): `src/http/oauth.mts`
- [Setup API](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/admin.mts): `src/http/admin.mts`

### MCP tools

- [MCP server](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/mcp.mts): `src/mcp.mts`
- [Tool registry](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/index.mts): `src/tools/index.mts`
- [Metadata tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/metadata.mts): `src/tools/metadata.mts`
- [SQL query tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/query.mts): `src/tools/query.mts`
- [Statement tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/statements.mts): `src/tools/statements.mts`
- [Ledger tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/ledgers.mts): `src/tools/ledgers.mts`
- [Inventory tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/inventory.mts): `src/tools/inventory.mts`
- [Voucher tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/vouchers.mts): `src/tools/vouchers.mts`
- [Context tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/context.mts): `src/tools/context.mts`
- [Master write tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/write.mts): `src/tools/write.mts`
- [Voucher write tools](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/voucher-write.mts): `src/tools/voucher-write.mts`
- [Tool helpers](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tools/shared.mts): `src/tools/shared.mts`

### Tally integration

- [Tally operations](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/index.mts): `src/tally/index.mts`
- [XML transport](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally/client.mts): `src/tally/client.mts`
- [XML templates](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/templates.mts): `src/templates.mts`
- [Data definitions](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/definition.mts): `src/definition.mts`

### Runtime state

- [Auth store](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/store.mts): `src/http/store.mts`
- [Realm resolver](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/http/realm.mts): `src/http/realm.mts`
- [Profile registry](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/profiles.mts): `src/profiles.mts`
- [Tally target](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/tally-target.mts): `src/tally-target.mts`
- [Result cache](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/database.mts): `src/database.mts`
- [Configuration](https://github.com/vimarsh244/tally-mcp-server/blob/dev/src/config.mts): `src/config.mts`

### Other components

- **MCP client**
- **Tally Prime**

## Connections

- MCP client → Server entry: starts local (evidence: `README.md`)
- MCP client → HTTP app: connects over HTTP (evidence: `README.md`)
- Server entry → MCP server: starts (evidence: `src/index.mts`)
- Web server → HTTP app: creates (evidence: `src/server.mts`)
- HTTP app → MCP HTTP route: registers (evidence: `src/http/app.mts`)
- HTTP app → OAuth routes: registers (evidence: `src/http/app.mts`)
- HTTP app → Realm resolver: creates resolver (evidence: `src/http/app.mts`)
- HTTP app → Setup API: registers (evidence: `src/http/app.mts`)
- OAuth routes → Auth store: uses (evidence: `src/http/oauth.mts`)
- MCP HTTP route → MCP server: serves (evidence: `src/http/mcp-route.mts`)
- MCP HTTP route → Realm resolver: resolves realm (evidence: `src/http/mcp-route.mts`)
- Realm resolver → Profile registry: looks up (evidence: `src/http/realm.mts`)
- Realm resolver → Tally target: selects target (evidence: `src/http/realm.mts`)
- Setup API → Profile registry: manages (evidence: `src/http/admin.mts`)
- Setup API → Tally operations: checks Tally (evidence: `src/http/admin.mts`)
- MCP server → Tool registry: registers tools (evidence: `src/mcp.mts`)
- Tool registry → Metadata tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → SQL query tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Statement tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Ledger tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Inventory tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Voucher tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Context tools: registers (evidence: `src/tools/index.mts`)
- Tool registry → Master write tools: registers optionally (evidence: `src/tools/index.mts`)
- Tool registry → Voucher write tools: registers optionally (evidence: `src/tools/index.mts`)
- Tool registry → Result cache: creates cache (evidence: `src/tools/index.mts`)
- Tool helpers → Result cache: caches results (evidence: `src/tools/shared.mts`)
- Metadata tools → Data definitions: reads definitions (evidence: `src/tools/metadata.mts`)
- SQL query tools → Tally operations: queries Tally (evidence: `src/tools/query.mts`)
- SQL query tools → Result cache: queries cache (evidence: `src/tools/query.mts`)
- Statement tools → Tally operations: fetches reports (evidence: `src/tools/statements.mts`)
- Ledger tools → Tally operations: queries Tally (evidence: `src/tools/ledgers.mts`)
- Inventory tools → Tally operations: queries Tally (evidence: `src/tools/inventory.mts`)
- Voucher tools → Tally operations: queries Tally (evidence: `src/tools/vouchers.mts`)
- Context tools → Tally operations: queries Tally (evidence: `src/tools/context.mts`)
- Master write tools → Tally operations: writes masters (evidence: `src/tools/write.mts`)
- Voucher write tools → Tally operations: writes vouchers (evidence: `src/tools/voucher-write.mts`)
- Tally operations → XML transport: uses transport (evidence: `src/tally/index.mts`)
- XML transport → XML templates: renders XML (evidence: `src/tally/client.mts`)
- XML transport → Tally target: reads target (evidence: `src/tally/client.mts`)
- XML transport → Tally Prime: posts XML (evidence: `README.md`)
- Tally operations → Data definitions: uses definitions
- Tool registry → Configuration: reads settings (evidence: `src/tools/index.mts`)