# jtab8/finance-skills architecture

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

- Interactive diagram: https://gitdiagram.com/jtab8/finance-skills
- Repository: https://github.com/jtab8/finance-skills

## Overview

FinanceSkills is an AI-agent finance toolkit: its main workflow is an agent selecting a finance skill, invoking a deterministic calculator through MCP, and receiving a structured result. The skills span financial reporting, audit/compliance, tax, risk, corporate finance, industry accounting, and analytics; connectors normalize external accounting exports for skill-ready use. The tree also includes a standalone audit detector and stdio/HTTP MCP entry points. Source excerpts show MCP discovery and dispatch, HTTP delegation, and connector output formats; unsampled skill cross-links and connector-to-calculator use are not asserted.

Main entry points: [`tools/mcp/server.py`](https://github.com/jtab8/finance-skills/blob/main/tools/mcp/server.py) (MCP stdio), [`tools/mcp/http_server.py`](https://github.com/jtab8/finance-skills/blob/main/tools/mcp/http_server.py) (MCP HTTP), [`financeskills_pkg/cli.py`](https://github.com/jtab8/finance-skills/blob/main/financeskills_pkg/cli.py) (Package CLI), [`tools/connectors/csv_mapper.py`](https://github.com/jtab8/finance-skills/blob/main/tools/connectors/csv_mapper.py) (CSV mapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_access["Agent access"]
  node_stdio_mcp["MCP stdio<br/>[server.py]"]
  node_http_mcp["MCP HTTP<br/>[http_server.py]"]
  node_cli["Package CLI<br/>[cli.py]"]
end

subgraph group_finance_skills["Finance skills"]
  node_skill_catalog["Finance skill catalog"]
  node_calc_financial["Analysis calculators<br/>[calculate.py]"]
  node_calc_reporting["Reporting calculators<br/>[calculate.py]"]
  node_calc_audit["Audit calculators<br/>[calculate.py]"]
  node_calc_tax["Tax calculators<br/>[calculate.py]"]
  node_calc_risk["Risk calculators<br/>[calculate.py]"]
  node_calc_corporate["Corporate finance<br/>[calculate.py]"]
  node_calc_industry["Industry calculators<br/>[calculate.py]"]
  node_calc_analytics["Analytics calculators<br/>[calculate.py]"]
end

subgraph group_data_ingestion["Data ingestion"]
  node_connectors["Export connectors"]
  node_csv_mapper["CSV mapper<br/>[csv_mapper.py]"]
end

subgraph group_audit_analysis["Audit analysis"]
  node_audit_detector["Audit detector<br/>[detector.py]"]
end

node_agent(("AI agent"))

node_agent -->|"calls tools"| node_stdio_mcp
node_agent -->|"posts requests"| node_http_mcp
node_stdio_mcp -->|"lists skills"| node_skill_catalog
node_stdio_mcp -->|"loads and dispatches"| node_calc_financial
node_stdio_mcp -->|"loads and dispatches"| node_calc_reporting
node_stdio_mcp -->|"loads and dispatches"| node_calc_audit
node_stdio_mcp -->|"loads and dispatches"| node_calc_tax
node_stdio_mcp -->|"loads and dispatches"| node_calc_risk
node_stdio_mcp -->|"loads and dispatches"| node_calc_corporate
node_stdio_mcp -->|"loads and dispatches"| node_calc_industry
node_stdio_mcp -->|"loads and dispatches"| node_calc_analytics
node_http_mcp -->|"delegates requests"| node_stdio_mcp
node_cli -->|"launches"| node_stdio_mcp
node_csv_mapper -->|"writes mapped CSV"| node_connectors

click node_stdio_mcp "https://github.com/jtab8/finance-skills/blob/main/tools/mcp/server.py"
click node_http_mcp "https://github.com/jtab8/finance-skills/blob/main/tools/mcp/http_server.py"
click node_cli "https://github.com/jtab8/finance-skills/blob/main/financeskills_pkg/cli.py"
click node_skill_catalog "https://github.com/jtab8/finance-skills/tree/main/skills"
click node_calc_financial "https://github.com/jtab8/finance-skills/blob/main/skills/financial-analysis/scripts/calculate.py"
click node_calc_reporting "https://github.com/jtab8/finance-skills/blob/main/skills/statement-preparation/scripts/calculate.py"
click node_calc_audit "https://github.com/jtab8/finance-skills/blob/main/skills/automated-reconciliation/scripts/calculate.py"
click node_calc_tax "https://github.com/jtab8/finance-skills/blob/main/skills/tax-planning/scripts/calculate.py"
click node_calc_risk "https://github.com/jtab8/finance-skills/blob/main/skills/risk-assessment/scripts/calculate.py"
click node_calc_corporate "https://github.com/jtab8/finance-skills/blob/main/skills/corporate-consolidation/scripts/calculate.py"
click node_calc_industry "https://github.com/jtab8/finance-skills/blob/main/skills/oil-gas-valuation/scripts/calculate.py"
click node_calc_analytics "https://github.com/jtab8/finance-skills/blob/main/skills/ai-anomaly-detection/scripts/calculate.py"
click node_connectors "https://github.com/jtab8/finance-skills/tree/main/tools/connectors"
click node_csv_mapper "https://github.com/jtab8/finance-skills/blob/main/tools/connectors/csv_mapper.py"
click node_audit_detector "https://github.com/jtab8/finance-skills/blob/main/projects/audit-system/core/detector.py"

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_mcp,node_http_mcp,node_cli toneBlue
class node_skill_catalog,node_calc_financial,node_calc_reporting,node_calc_audit,node_calc_tax,node_calc_risk,node_calc_corporate,node_calc_industry,node_calc_analytics toneAmber
class node_connectors,node_csv_mapper toneMint
class node_audit_detector toneRose
class node_agent toneIndigo
```

## Components

### Agent access

- [MCP stdio](https://github.com/jtab8/finance-skills/blob/main/tools/mcp/server.py): `tools/mcp/server.py`
- [MCP HTTP](https://github.com/jtab8/finance-skills/blob/main/tools/mcp/http_server.py): `tools/mcp/http_server.py`
- [Package CLI](https://github.com/jtab8/finance-skills/blob/main/financeskills_pkg/cli.py): `financeskills_pkg/cli.py`

### Finance skills

- [Finance skill catalog](https://github.com/jtab8/finance-skills/tree/main/skills): `skills`
- [Analysis calculators](https://github.com/jtab8/finance-skills/blob/main/skills/financial-analysis/scripts/calculate.py): `skills/financial-analysis/scripts/calculate.py`
- [Reporting calculators](https://github.com/jtab8/finance-skills/blob/main/skills/statement-preparation/scripts/calculate.py): `skills/statement-preparation/scripts/calculate.py`
- [Audit calculators](https://github.com/jtab8/finance-skills/blob/main/skills/automated-reconciliation/scripts/calculate.py): `skills/automated-reconciliation/scripts/calculate.py`
- [Tax calculators](https://github.com/jtab8/finance-skills/blob/main/skills/tax-planning/scripts/calculate.py): `skills/tax-planning/scripts/calculate.py`
- [Risk calculators](https://github.com/jtab8/finance-skills/blob/main/skills/risk-assessment/scripts/calculate.py): `skills/risk-assessment/scripts/calculate.py`
- [Corporate finance](https://github.com/jtab8/finance-skills/blob/main/skills/corporate-consolidation/scripts/calculate.py): `skills/corporate-consolidation/scripts/calculate.py`
- [Industry calculators](https://github.com/jtab8/finance-skills/blob/main/skills/oil-gas-valuation/scripts/calculate.py): `skills/oil-gas-valuation/scripts/calculate.py`
- [Analytics calculators](https://github.com/jtab8/finance-skills/blob/main/skills/ai-anomaly-detection/scripts/calculate.py): `skills/ai-anomaly-detection/scripts/calculate.py`

### Data ingestion

- [Export connectors](https://github.com/jtab8/finance-skills/tree/main/tools/connectors): `tools/connectors`
- [CSV mapper](https://github.com/jtab8/finance-skills/blob/main/tools/connectors/csv_mapper.py): `tools/connectors/csv_mapper.py`

### Audit analysis

- [Audit detector](https://github.com/jtab8/finance-skills/blob/main/projects/audit-system/core/detector.py): `projects/audit-system/core/detector.py`

### Other components

- **AI agent**

## Connections

- AI agent → MCP stdio: calls tools (evidence: `tools/mcp/server.py`)
- AI agent → MCP HTTP: posts requests (evidence: `tools/mcp/http_server.py`)
- MCP stdio → Finance skill catalog: lists skills (evidence: `tools/mcp/server.py`)
- MCP stdio → Analysis calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Reporting calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Audit calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Tax calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Risk calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Corporate finance: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Industry calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP stdio → Analytics calculators: loads and dispatches (evidence: `tools/mcp/server.py`)
- MCP HTTP → MCP stdio: delegates requests (evidence: `tools/mcp/http_server.py`)
- Package CLI → MCP stdio: launches (evidence: `financeskills_pkg/cli.py`)
- CSV mapper → Export connectors: writes mapped CSV (evidence: `tools/connectors/csv_mapper.py`)
