enrichmcp AGENTS.md

Repository Overview: EnrichMCP

This document summarizes the structure, purpose, and usage patterns found in the enrichmcp repository. The project provides a framework that exposes structured data models to AI agents via the Model Context Protocol (MCP). Below is a detailed look at the repository's key components, build instructions, examples, and development practices.

1. Purpose and Scope

The README describes EnrichMCP as "The ORM for AI Agents - Turn your data model into a semantic MCP layer" and highlights its goals:

• generate typed tools from data models
• manage relationships between entities
• provide schema discovery for AI agents
• validate inputs and outputs using Pydantic
• support any backend data source

These points appear in the README between lines 11 and 21【F:README.md†L11-L21】.

The framework allows developers to define Pydantic models (entities) and relationships, register them with an EnrichMCP application, and automatically expose resources for AI consumption. It also offers optional SQLAlchemy integration to convert existing ORM models into EnrichMCP entities.

2. Project Layout

/ (repo root)
├── README.md          – introduction and quickstart
├── Makefile           – common development commands
├── pyproject.toml     – package metadata and tooling config
├── docs/              – user documentation (MkDocs site)
├── examples/          – runnable examples
├── src/enrichmcp/     – library implementation
└── tests/             – unit tests

2.1 Important Files

• pyproject.toml defines project metadata, required Python version, dependencies, optional dev tools, and tooling configuration including Ruff, Pyright, and coverage settings【F:pyproject.toml†L1-L159】.
• Makefile contains tasks for setup, linting, tests, docs, and CI usage. For example, running make setup creates a virtual environment and installs dependencies【F:Makefile†L18-L24】.
• docs/ hosts Markdown guides describing core concepts, examples, pagination, and SQLAlchemy integration. The site is served via MkDocs.
• src/enrichmcp/ implements the framework’s core logic. Modules include:
  • app.py – the main EnrichMCP application class.
  • entity.py – base EnrichModel providing serialization and description helpers.
  • relationship.py – descriptor for defining relationships and registering resolvers.
  • pagination.py – helper classes (PageResult, CursorResult, etc.).
  • context.py – thin wrapper around FastMCP’s context object.
  • lifespan.py – helper to combine async lifespans.
  • sqlalchemy/ – optional SQLAlchemy integration utilities.
• examples/ demonstrates usage patterns such as a hello world API, a shop API (in-memory and SQLite backed), an OpenAI chat agent, and SQLAlchemy integration.