# mizcausevic-dev/mcp-aeo-server architecture

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

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/mcp-aeo-server
- Repository: https://github.com/mizcausevic-dev/mcp-aeo-server

## Overview

#### Purpose and principal workflow
This Node.js MCP server lets an MCP-compatible AI client request AEO Protocol declarations from web origins. The client initiates the workflow by invoking one of the server’s advertised tools over stdio; for fetch, inspect, and claim lookup, the server constructs the origin’s well-known URL, fetches and validates the document, then returns the requested representation. A URL-only tool computes the URL without making a network request.

#### Components

##### MCP runtime and tool interface
- **MCP server entry and dispatch** — `src/server.ts`: Builds the MCP server, registers tool-list and tool-call handlers, routes calls to handlers, serializes results or errors, and starts the stdio connection when run as the executable.
- **Tool descriptors** — `src/tools.ts`: Defines the four tools’ names, descriptions, and input JSON Schemas, which the server returns to clients.
- **MCP-compatible client** — `null` (external): An agent client such as Claude Desktop or Cursor connects over stdio, discovers the tools, and invokes them.
- **MCP SDK and stdio transport** — `null` (external dependency): The MCP SDK supplies the server and stdio transport used by the entry point to communicate with clients.

##### AEO document access and operations
- **AEO document discovery and validation** — `src/document.ts`: Builds the `/.well-known/aeo.json` URL, fetches it with an AEO/JSON Accept header and timeout, and parses it against strict Zod schemas for AEO v0.1.
- **Tool result handlers** — `src/server.ts`: Implements fetch, inspect, claim lookup, and URL-only results; inspect summarizes document fields, while claim lookup returns the match or available IDs when none is found.
- **AEO origin** — `null` (external): A website origin supplies the AEO document at its well-known URL; the server accesses it directly over HTTP.

##### Published tool documentation
- **MCP Tool Cards** — `tool-cards/aeo-fetch.json`: The repository includes conforming Tool Card documents for the tools; the README describes them as shipped alongside the package. The sampled code does not establish that the running server loads or serves these files.

#### Relationships
- **MCP-compatible client -> MCP SDK and stdio transport**: Connects and sends tool-list or tool-call requests over stdio; the README documents stdio MCP clients and `src/server.ts` connects the SDK transport.
- **MCP SDK and stdio transport -> MCP server entry and dispatch**: Delivers requests to the registered handlers; `src/server.ts` registers the MCP request handlers.
- **MCP server entry and dispatch -> Tool descriptors**: Returns descriptors in response to a tool-list request; `src/server.ts` imports and returns `toolDescriptors`.
- **MCP server entry and dispatch -> Tool result handlers**: Dispatches tool-call requests by tool name; `src/server.ts` maps names to handlers.
- **Tool result handlers -> AEO document discovery and validation**: Fetch, inspect, and claim handlers request a document; the URL-only handler instead calls URL construction directly, as implemented in `src/server.ts`.
- **AEO document discovery and validation -> AEO origin**: Fetches the constructed well-known URL over HTTP and parses the response; `src/document.ts` implements the request and validation.
- **Tool result handlers -> MCP server entry and dispatch**: Returns serialized result text, or an error that the dispatcher wraps as MCP content; `src/server.ts` implements both handlers and response wrapping.
- **MCP server entry and dispatch -> MCP SDK and stdio transport**: Connects the server to the stdio transport at startup; `src/server.ts` calls `server.connect(transport)`.
- **MCP Tool Cards -> MCP-compatible client**: The README documents the cards as conforming tool documentation, but no runtime delivery path is established by the sampled code.

#### Coverage limits
The source sample does not show Tool Card loading or publication, and does not establish client-specific behavior beyond the documented stdio MCP interface. It also does not establish network restrictions or additional document-serving behavior at AEO origins.

Main entry points: [`src/server.ts`](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/server.ts) (MCP server), [`src/document.ts`](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/document.ts) (AEO discovery and validation), [`tool-cards/aeo-fetch.json`](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/tool-cards/aeo-fetch.json) (MCP Tool Cards), [`src/tools.ts`](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/tools.ts) (Tool descriptors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mcp["MCP Interface"]
  node_client(("MCP client<br/>External client"))
  node_stdio["MCP SDK and stdio<br/>External dependency"]
  node_server["MCP server<br/>Runtime entry"]
  node_descriptors["Tool descriptors<br/>Tool schemas"]
  node_handlers["Tool handlers<br/>Result handlers"]
end

subgraph group_aeo["AEO Document Access"]
  node_document["AEO discovery and validation<br/>Document access"]
  node_origin(("AEO origin<br/>External website"))
end

subgraph group_docs["Published Documentation"]
  node_toolcards["MCP Tool Cards<br/>Tool documentation"]
end

node_client -->|"sends requests"| node_stdio
node_stdio -->|"delivers requests"| node_server
node_server -->|"returns descriptors"| node_descriptors
node_server -->|"dispatches calls"| node_handlers
node_handlers -->|"requests document"| node_document
node_document -->|"fetches and validates"| node_origin
node_handlers -->|"returns result or error"| node_server
node_server -->|"connects transport"| node_stdio
node_toolcards -.->|"documents tools"| node_client

click node_server "https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/server.ts"
click node_descriptors "https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/tools.ts"
click node_handlers "https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/server.ts"
click node_document "https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/document.ts"
click node_toolcards "https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/tool-cards/aeo-fetch.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_client,node_stdio,node_server,node_descriptors,node_handlers toneBlue
class node_document,node_origin toneAmber
class node_toolcards toneMint
```

## Components

### MCP Interface

- **MCP client**: External client
- **MCP SDK and stdio**: External dependency
- [MCP server](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/server.ts): Runtime entry · `src/server.ts`
- [Tool descriptors](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/tools.ts): Tool schemas · `src/tools.ts`
- [Tool handlers](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/server.ts): Result handlers · `src/server.ts`

### AEO Document Access

- [AEO discovery and validation](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/src/document.ts): Document access · `src/document.ts`
- **AEO origin**: External website

### Published Documentation

- [MCP Tool Cards](https://github.com/mizcausevic-dev/mcp-aeo-server/blob/main/tool-cards/aeo-fetch.json): Tool documentation · The sampled code does not establish runtime loading or serving. · `tool-cards/aeo-fetch.json`

## Connections

- MCP client → MCP SDK and stdio: sends requests · Tool-list and tool-call requests over stdio.
- MCP SDK and stdio → MCP server: delivers requests
- MCP server → Tool descriptors: returns descriptors
- MCP server → Tool handlers: dispatches calls
- Tool handlers → AEO discovery and validation: requests document · Fetch, inspect, and claim handlers request a document; the URL-only handler constructs the URL directly.
- AEO discovery and validation → AEO origin: fetches and validates · Requests the well-known URL over HTTP and parses the response.
- Tool handlers → MCP server: returns result or error · The dispatcher wraps the response as MCP content.
- MCP server → MCP SDK and stdio: connects transport
- MCP Tool Cards → MCP client: documents tools · Documented as conforming tool documentation; no runtime delivery path is established.