mizcausevic-dev/mcp-aeo-server

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.