# faeralan/mcp-arca-afip architecture

> Architecture diagram of the GitHub repository faeralan/mcp-arca-afip, 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/faeralan/mcp-arca-afip
- Repository: https://github.com/faeralan/mcp-arca-afip

## Overview

mcp-arca-afip is a local MCP server for searching and retrieving official ARCA/AFIP web-service documentation. Its main user flow is an MCP client calling a registered tool: search embeds a query and combines semantic and BM25 results, while the listing, service-detail, and full-document tools expose complementary views of the local index. A separate ingestion workflow crawls, parses, chunks, and embeds source documents into that index. The README documents the product capabilities; ingestion wiring is only partly evidenced by the sampled files, so uncertain links are dashed.

Main entry points: [`src/server.ts`](https://github.com/faeralan/mcp-arca-afip/blob/main/src/server.ts) (Tool server), [`src/services/vector-store.ts`](https://github.com/faeralan/mcp-arca-afip/blob/main/src/services/vector-store.ts) (Hybrid retrieval), [`src/tools/search-docs.tool.ts`](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/search-docs.tool.ts) (Search docs), [`src/tools/get-document.tool.ts`](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/get-document.tool.ts) (Get document)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP interface"]
  node_server["Tool server<br/>[server.ts]"]
  node_search_tool["Search docs"]
  node_list_tool["List services"]
  node_detail_tool["Service detail"]
  node_document_tool["Get document"]
  node_formatter["Safe formatting<br/>[format.ts]"]
end

subgraph group_query["Query and retrieval"]
  node_embedder["Query embeddings<br/>[embedder.ts]"]
  node_retrieval["Hybrid retrieval<br/>[vector-store.ts]"]
end

subgraph group_index["Local index"]
  node_index_db[("Documentation index")]
end

subgraph group_ingest["Documentation ingestion"]
  node_crawl["Source crawler<br/>[crawl.ts]"]
  node_parser["Document parser<br/>[parse.ts]"]
  node_chunker["Section chunker<br/>[chunk.ts]"]
  node_ingest_embed["Passage embeddings<br/>[embed.ts]"]
  node_index_builder["Index builder<br/>[build-index.ts]"]
end

node_client(("MCP client"))
node_afip["ARCA/AFIP docs"]

node_client -->|"sends requests"| node_server
node_server -->|"dispatches search"| node_search_tool
node_server -->|"dispatches listing"| node_list_tool
node_server -->|"dispatches detail"| node_detail_tool
node_server -->|"dispatches document"| node_document_tool
node_search_tool -->|"embeds query"| node_embedder
node_search_tool -->|"searches index"| node_retrieval
node_search_tool -->|"formats results"| node_formatter
node_document_tool -->|"reads chunks"| node_retrieval
node_document_tool -->|"formats document"| node_formatter
node_list_tool -->|"lists services"| node_retrieval
node_detail_tool -->|"loads metadata"| node_retrieval
node_retrieval -->|"reads index"| node_index_db
node_afip -.->|"provides documents"| node_crawl
node_crawl -.->|"supplies downloads"| node_parser
node_parser -.->|"yields sections"| node_chunker
node_chunker -.->|"supplies chunks"| node_ingest_embed
node_ingest_embed -->|"reuses embeddings"| node_embedder
node_index_builder -.->|"builds index"| node_index_db

click node_server "https://github.com/faeralan/mcp-arca-afip/blob/main/src/server.ts"
click node_search_tool "https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/search-docs.tool.ts"
click node_list_tool "https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/list-web-services.tool.ts"
click node_detail_tool "https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/get-web-service.tool.ts"
click node_document_tool "https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/get-document.tool.ts"
click node_formatter "https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/format.ts"
click node_embedder "https://github.com/faeralan/mcp-arca-afip/blob/main/src/services/embedder.ts"
click node_retrieval "https://github.com/faeralan/mcp-arca-afip/blob/main/src/services/vector-store.ts"
click node_index_db "https://github.com/faeralan/mcp-arca-afip/tree/main/data"
click node_crawl "https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/crawl.ts"
click node_parser "https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/parse.ts"
click node_chunker "https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/chunk.ts"
click node_ingest_embed "https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/embed.ts"
click node_index_builder "https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/build-index.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_server,node_search_tool,node_list_tool,node_detail_tool,node_document_tool,node_formatter,node_client toneBlue
class node_embedder,node_retrieval toneAmber
class node_index_db toneMint
class node_crawl,node_parser,node_chunker,node_ingest_embed,node_index_builder toneRose
class node_afip toneIndigo
```

## Components

### MCP interface

- [Tool server](https://github.com/faeralan/mcp-arca-afip/blob/main/src/server.ts): `src/server.ts`
- [Search docs](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/search-docs.tool.ts): `src/tools/search-docs.tool.ts`
- [List services](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/list-web-services.tool.ts): `src/tools/list-web-services.tool.ts`
- [Service detail](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/get-web-service.tool.ts): `src/tools/get-web-service.tool.ts`
- [Get document](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/get-document.tool.ts): `src/tools/get-document.tool.ts`
- [Safe formatting](https://github.com/faeralan/mcp-arca-afip/blob/main/src/tools/format.ts): `src/tools/format.ts`

### Query and retrieval

- [Query embeddings](https://github.com/faeralan/mcp-arca-afip/blob/main/src/services/embedder.ts): `src/services/embedder.ts`
- [Hybrid retrieval](https://github.com/faeralan/mcp-arca-afip/blob/main/src/services/vector-store.ts): `src/services/vector-store.ts`

### Local index

- [Documentation index](https://github.com/faeralan/mcp-arca-afip/tree/main/data): `data`

### Documentation ingestion

- [Source crawler](https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/crawl.ts): `ingest/crawl.ts`
- [Document parser](https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/parse.ts): `ingest/parse.ts`
- [Section chunker](https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/chunk.ts): `ingest/chunk.ts`
- [Passage embeddings](https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/embed.ts): `ingest/embed.ts`
- [Index builder](https://github.com/faeralan/mcp-arca-afip/blob/main/ingest/build-index.ts): `ingest/build-index.ts`

### Other components

- **MCP client**
- **ARCA/AFIP docs**

## Connections

- MCP client → Tool server: sends requests (evidence: `README.md`)
- Tool server → Search docs: dispatches search (evidence: `src/server.ts`)
- Tool server → List services: dispatches listing (evidence: `src/server.ts`)
- Tool server → Service detail: dispatches detail (evidence: `src/server.ts`)
- Tool server → Get document: dispatches document (evidence: `src/server.ts`)
- Search docs → Query embeddings: embeds query (evidence: `src/tools/search-docs.tool.ts`)
- Search docs → Hybrid retrieval: searches index (evidence: `src/tools/search-docs.tool.ts`)
- Search docs → Safe formatting: formats results (evidence: `src/tools/search-docs.tool.ts`)
- Get document → Hybrid retrieval: reads chunks (evidence: `src/tools/get-document.tool.ts`)
- Get document → Safe formatting: formats document (evidence: `src/tools/get-document.tool.ts`)
- List services → Hybrid retrieval: lists services (evidence: `src/tools/list-web-services.tool.ts`)
- Service detail → Hybrid retrieval: loads metadata (evidence: `src/tools/get-web-service.tool.ts`)
- Hybrid retrieval → Documentation index: reads index (evidence: `src/services/vector-store.ts`)
- ARCA/AFIP docs → Source crawler: provides documents (evidence: `README.md`)
- Source crawler → Document parser: supplies downloads (evidence: `ingest/parse.ts`)
- Document parser → Section chunker: yields sections (evidence: `ingest/chunk.ts`)
- Section chunker → Passage embeddings: supplies chunks (evidence: `ingest/embed.ts`)
- Passage embeddings → Query embeddings: reuses embeddings (evidence: `ingest/embed.ts`)
- Index builder → Documentation index: builds index (evidence: `README.md`)
