# tech-armstrong/mf-nav-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/tech-armstrong/mf-nav-mcp
- Repository: https://github.com/tech-armstrong/mf-nav-mcp

## Overview

This repository combines a read-only NAV analytics MCP server with a holdings-enrichment CLI and scripts that maintain benchmark-index data. The primary user workflow is a client request to the MCP server, which reads fund and index parquet data and returns discovery or performance analytics; optional holdings enrichment produces spreadsheet and JSON outputs. The server is documented as self-contained, so its tool capabilities share one implementation path. Some subsystem links are based on README documentation or the SOURCE INDEX; unsampled implementation details are not assumed.

Main entry points: [`holdings_enricher/main.py`](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/main.py) (Enrichment CLI), [`server.py`](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py) (MCP server), [`data`](https://github.com/tech-armstrong/mf-nav-mcp/tree/main/data) (Index parquet), [`holdings_enricher/src/api_client.py`](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/api_client.py) (Advisorkhoj client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analytics["NAV analytics server"]
  node_server["MCP server<br/>[server.py]"]
  node_fundtools["Fund analytics<br/>[server.py]"]
  node_indextools["Index analytics<br/>[server.py]"]
  node_holdings_tools["Holdings analytics<br/>[server.py]"]
  node_oauth["OAuth auth<br/>[server.py]"]
end

subgraph group_data["Analytics data"]
  node_navdata[("NAV parquet")]
  node_indexdata[("Index parquet")]
  node_holdingsjson["Holdings JSON<br/>[fund_holdings.json]"]
end

subgraph group_holdings["Holdings enrichment"]
  node_enrich_cli["Enrichment CLI<br/>[main.py]"]
  node_api_source["API source adapter<br/>[api_source.py]"]
  node_api_client["Advisorkhoj client<br/>[api_client.py]"]
  node_builder["Record builder<br/>[builder.py]"]
  node_enricher["Holdings enricher<br/>[enricher.py]"]
  node_matcher["Stock matcher<br/>[matcher.py]"]
  node_validator["Weight validator<br/>[validator.py]"]
  node_nav_resolver["NAV name resolver<br/>[nav_names.py]"]
  node_xlsx_writer["Workbook export<br/>[writer.py]"]
  node_json_export["Profile JSON export<br/>[json_export.py]"]
end

subgraph group_indices["Index maintenance"]
  node_xlsx_parser["Workbook importer"]
  node_daily_append["Daily close importer"]
end

node_client(("MCP client"))
node_advisorkhoj["Advisorkhoj API"]

node_client -->|"requests tools"| node_server
node_server -->|"registers tools"| node_fundtools
node_server -->|"registers tools"| node_indextools
node_server -->|"exposes holdings"| node_holdings_tools
node_server -->|"configures auth"| node_oauth
node_server -->|"queries parquet"| node_navdata
node_server -->|"reads closes"| node_indexdata
node_server -->|"loads holdings"| node_holdingsjson
node_enrich_cli -->|"uses adapter"| node_api_source
node_enrich_cli -->|"uses client"| node_api_client
node_enrich_cli -->|"uses builder"| node_builder
node_enrich_cli -->|"enriches records"| node_enricher
node_enrich_cli -->|"uses matcher"| node_matcher
node_enrich_cli -->|"validates weights"| node_validator
node_enrich_cli -->|"writes workbook"| node_xlsx_writer
node_enrich_cli -->|"exports profiles"| node_json_export
node_api_source -->|"requests portfolios"| node_api_client
node_advisorkhoj -.->|"serves API data"| node_api_client
node_enricher -->|"resolves stocks"| node_matcher
node_json_export -->|"resolves fund names"| node_nav_resolver
node_xlsx_parser -->|"writes history"| node_indexdata
node_xlsx_parser -->|"writes master"| node_indexdata
node_daily_append -->|"appends closes"| node_indexdata

click node_server "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py"
click node_fundtools "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py"
click node_indextools "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py"
click node_holdings_tools "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py"
click node_oauth "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py"
click node_navdata "https://github.com/tech-armstrong/mf-nav-mcp/tree/main/data"
click node_indexdata "https://github.com/tech-armstrong/mf-nav-mcp/tree/main/data"
click node_holdingsjson "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/data/fund_holdings.json"
click node_enrich_cli "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/main.py"
click node_api_source "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/api_source.py"
click node_api_client "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/api_client.py"
click node_builder "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/builder.py"
click node_enricher "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/enricher.py"
click node_matcher "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/matcher.py"
click node_validator "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/validator.py"
click node_nav_resolver "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/nav_names.py"
click node_xlsx_writer "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/writer.py"
click node_json_export "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/json_export.py"
click node_xlsx_parser "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/Index/parse_index_xlsx.py"
click node_daily_append "https://github.com/tech-armstrong/mf-nav-mcp/blob/main/Index/append_daily_close.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_server,node_fundtools,node_indextools,node_holdings_tools,node_oauth,node_client toneBlue
class node_navdata,node_indexdata,node_holdingsjson toneAmber
class node_enrich_cli,node_api_source,node_api_client,node_builder,node_enricher,node_matcher,node_validator,node_nav_resolver,node_xlsx_writer,node_json_export,node_advisorkhoj toneMint
class node_xlsx_parser,node_daily_append toneRose
```

## Components

### NAV analytics server

- [MCP server](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py): `server.py`
- [Fund analytics](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py): `server.py`
- [Index analytics](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py): `server.py`
- [Holdings analytics](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py): `server.py`
- [OAuth auth](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/server.py): `server.py`

### Analytics data

- [NAV parquet](https://github.com/tech-armstrong/mf-nav-mcp/tree/main/data): `data`
- [Index parquet](https://github.com/tech-armstrong/mf-nav-mcp/tree/main/data): `data`
- [Holdings JSON](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/data/fund_holdings.json): `data/fund_holdings.json`

### Holdings enrichment

- [Enrichment CLI](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/main.py): `holdings_enricher/main.py`
- [API source adapter](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/api_source.py): `holdings_enricher/src/api_source.py`
- [Advisorkhoj client](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/api_client.py): `holdings_enricher/src/api_client.py`
- [Record builder](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/builder.py): `holdings_enricher/src/builder.py`
- [Holdings enricher](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/enricher.py): `holdings_enricher/src/enricher.py`
- [Stock matcher](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/matcher.py): `holdings_enricher/src/matcher.py`
- [Weight validator](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/validator.py): `holdings_enricher/src/validator.py`
- [NAV name resolver](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/nav_names.py): `holdings_enricher/src/nav_names.py`
- [Workbook export](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/writer.py): `holdings_enricher/src/writer.py`
- [Profile JSON export](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/holdings_enricher/src/json_export.py): `holdings_enricher/src/json_export.py`

### Index maintenance

- [Workbook importer](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/Index/parse_index_xlsx.py): `Index/parse_index_xlsx.py`
- [Daily close importer](https://github.com/tech-armstrong/mf-nav-mcp/blob/main/Index/append_daily_close.py): `Index/append_daily_close.py`

### Other components

- **MCP client**
- **Advisorkhoj API**

## Connections

- MCP client → MCP server: requests tools (evidence: `README.md`)
- MCP server → Fund analytics: registers tools (evidence: `README.md`)
- MCP server → Index analytics: registers tools (evidence: `README.md`)
- MCP server → Holdings analytics: exposes holdings (evidence: `server.py`)
- MCP server → OAuth auth: configures auth (evidence: `README.md`)
- MCP server → NAV parquet: queries parquet (evidence: `README.md`)
- MCP server → Index parquet: reads closes (evidence: `README.md`)
- MCP server → Holdings JSON: loads holdings (evidence: `server.py`)
- Enrichment CLI → API source adapter: uses adapter (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Advisorkhoj client: uses client (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Record builder: uses builder (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Holdings enricher: enriches records (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Stock matcher: uses matcher (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Weight validator: validates weights (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Workbook export: writes workbook (evidence: `holdings_enricher/main.py`)
- Enrichment CLI → Profile JSON export: exports profiles (evidence: `holdings_enricher/main.py`)
- API source adapter → Advisorkhoj client: requests portfolios (evidence: `holdings_enricher/src/api_source.py`)
- Advisorkhoj API → Advisorkhoj client: serves API data (evidence: `holdings_enricher/src/api_client.py`)
- Holdings enricher → Stock matcher: resolves stocks (evidence: `holdings_enricher/src/enricher.py`)
- Profile JSON export → NAV name resolver: resolves fund names (evidence: `holdings_enricher/src/json_export.py`)
- Workbook importer → Index parquet: writes history (evidence: `Index/parse_index_xlsx.py`)
- Workbook importer → Index parquet: writes master (evidence: `Index/parse_index_xlsx.py`)
- Daily close importer → Index parquet: appends closes (evidence: `Index/append_daily_close.py`)
