# baguskto/saham-mcp architecture

> Architecture diagram of the GitHub repository baguskto/saham-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/baguskto/saham-mcp
- Repository: https://github.com/baguskto/saham-mcp

## Overview

Baguskto Saham is an MCP server that exposes Indonesian stock-market data and analysis to AI clients. The main workflow is a client tool request handled by the MCP server, which uses cache and data sources to produce a response. Historical data has a distinct fetch, parse, and local-cache path; other documented capabilities include market overview, stock information, sector performance, search, comparison, and technical analysis. The README documents these tools and source priorities, but excerpts omit much of their handler wiring, so uncertain links are left out.

Main entry points: [`src/server/index.ts`](https://github.com/baguskto/saham-mcp/blob/main/src/server/index.ts) (MCP server), [`src/data-sources/base.ts`](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/base.ts) (Source manager), [`src/services/historical-data-service.ts`](https://github.com/baguskto/saham-mcp/blob/main/src/services/historical-data-service.ts) (Historical data service), [`src/data-sources/yahoo-finance.ts`](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/yahoo-finance.ts) (Yahoo Finance)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["MCP Access"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_server["MCP server<br/>[index.ts]"]
end

subgraph group_tools["Stock Tools"]
  node_tools["Stock tool handlers<br/>[index.ts]"]
  node_analysis["Technical analysis"]
  node_cache[("Response cache<br/>[index.ts]")]
end

subgraph group_sources["Data Sources"]
  node_manager["Source manager<br/>[base.ts]"]
  node_sourceinit["Source initialization<br/>[index.ts]"]
  node_yahoo["Yahoo Finance<br/>[yahoo-finance.ts]"]
  node_scraper["Web fallback<br/>[web-scraper.ts]"]
  node_ghsource["GitHub dataset source<br/>[github-dataset.ts]"]
end

subgraph group_history["Historical Data"]
  node_historical["Historical data service"]
  node_ghapi["GitHub API client<br/>[github-api.ts]"]
  node_parser["CSV parser<br/>[csv-parser.ts]"]
  node_localdata[("Historical JSON<br/>[BBCA.json]")]
  node_metadata[("Stock metadata<br/>[BBCA.json]")]
end

node_client(("AI client"))
node_yahooapi{{"Yahoo Finance service"}}
node_web{{"Market websites"}}
node_ghdataset{{"Dataset-Saham-IDX"}}

node_client -->|"requests tools"| node_server
node_cli -->|"starts"| node_server
node_server -->|"returns results"| node_client
node_server -->|"dispatches tools"| node_tools
node_server -->|"reads and writes"| node_cache
node_server -->|"requests market data"| node_manager
node_server -->|"uses analysis"| node_analysis
node_sourceinit -->|"registers sources"| node_manager
node_manager -->|"dispatches historical"| node_ghsource
node_manager -->|"dispatches live data"| node_yahoo
node_manager -.->|"fallback dispatch"| node_scraper
node_yahoo -->|"fetches quotes"| node_yahooapi
node_scraper -.->|"scrapes data"| node_web
node_historical -->|"requests dataset data"| node_ghapi
node_historical -->|"parses CSV"| node_parser
node_historical -->|"reads and writes"| node_localdata
node_historical -->|"reads and writes"| node_metadata
node_ghapi -->|"fetches files"| node_ghdataset

click node_cli "https://github.com/baguskto/saham-mcp/blob/main/src/cli.ts"
click node_server "https://github.com/baguskto/saham-mcp/blob/main/src/server/index.ts"
click node_tools "https://github.com/baguskto/saham-mcp/blob/main/src/server/index.ts"
click node_analysis "https://github.com/baguskto/saham-mcp/blob/main/src/services/technical-analysis.ts"
click node_cache "https://github.com/baguskto/saham-mcp/blob/main/src/cache/index.ts"
click node_manager "https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/base.ts"
click node_sourceinit "https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/index.ts"
click node_yahoo "https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/yahoo-finance.ts"
click node_scraper "https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/web-scraper.ts"
click node_ghsource "https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/github-dataset.ts"
click node_historical "https://github.com/baguskto/saham-mcp/blob/main/src/services/historical-data-service.ts"
click node_ghapi "https://github.com/baguskto/saham-mcp/blob/main/src/utils/github-api.ts"
click node_parser "https://github.com/baguskto/saham-mcp/blob/main/src/services/csv-parser.ts"
click node_localdata "https://github.com/baguskto/saham-mcp/blob/main/data/historical/BBCA.json"
click node_metadata "https://github.com/baguskto/saham-mcp/blob/main/data/metadata/BBCA.json"

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_cli,node_server,node_client toneBlue
class node_tools,node_analysis,node_cache toneAmber
class node_manager,node_sourceinit,node_yahoo,node_scraper,node_ghsource toneMint
class node_historical,node_ghapi,node_parser,node_localdata,node_metadata toneRose
class node_yahooapi,node_web,node_ghdataset toneIndigo
```

## Components

### MCP Access

- [CLI entry](https://github.com/baguskto/saham-mcp/blob/main/src/cli.ts): `src/cli.ts`
- [MCP server](https://github.com/baguskto/saham-mcp/blob/main/src/server/index.ts): `src/server/index.ts`

### Stock Tools

- [Stock tool handlers](https://github.com/baguskto/saham-mcp/blob/main/src/server/index.ts): `src/server/index.ts`
- [Technical analysis](https://github.com/baguskto/saham-mcp/blob/main/src/services/technical-analysis.ts): `src/services/technical-analysis.ts`
- [Response cache](https://github.com/baguskto/saham-mcp/blob/main/src/cache/index.ts): `src/cache/index.ts`

### Data Sources

- [Source manager](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/base.ts): `src/data-sources/base.ts`
- [Source initialization](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/index.ts): `src/data-sources/index.ts`
- [Yahoo Finance](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/yahoo-finance.ts): `src/data-sources/yahoo-finance.ts`
- [Web fallback](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/web-scraper.ts): `src/data-sources/web-scraper.ts`
- [GitHub dataset source](https://github.com/baguskto/saham-mcp/blob/main/src/data-sources/github-dataset.ts): `src/data-sources/github-dataset.ts`

### Historical Data

- [Historical data service](https://github.com/baguskto/saham-mcp/blob/main/src/services/historical-data-service.ts): `src/services/historical-data-service.ts`
- [GitHub API client](https://github.com/baguskto/saham-mcp/blob/main/src/utils/github-api.ts): `src/utils/github-api.ts`
- [CSV parser](https://github.com/baguskto/saham-mcp/blob/main/src/services/csv-parser.ts): `src/services/csv-parser.ts`
- [Historical JSON](https://github.com/baguskto/saham-mcp/blob/main/data/historical/BBCA.json): `data/historical/BBCA.json`
- [Stock metadata](https://github.com/baguskto/saham-mcp/blob/main/data/metadata/BBCA.json): `data/metadata/BBCA.json`

### Other components

- **AI client**
- **Yahoo Finance service**
- **Market websites**
- **Dataset-Saham-IDX**

## Connections

- AI client → MCP server: requests tools
- CLI entry → MCP server: starts
- MCP server → AI client: returns results
- MCP server → Stock tool handlers: dispatches tools
- MCP server → Response cache: reads and writes
- MCP server → Source manager: requests market data
- MCP server → Technical analysis: uses analysis
- Source initialization → Source manager: registers sources
- Source manager → GitHub dataset source: dispatches historical
- Source manager → Yahoo Finance: dispatches live data
- Source manager → Web fallback: fallback dispatch
- Yahoo Finance → Yahoo Finance service: fetches quotes
- Web fallback → Market websites: scrapes data
- Historical data service → GitHub API client: requests dataset data
- Historical data service → CSV parser: parses CSV
- Historical data service → Historical JSON: reads and writes
- Historical data service → Stock metadata: reads and writes
- GitHub API client → Dataset-Saham-IDX: fetches files