[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-featureform--enrichmcp":3,"tool-featureform--enrichmcp":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":70,"readme_en":71,"readme_zh":72,"quickstart_zh":73,"use_case_zh":74,"hero_image_url":75,"owner_login":76,"owner_name":77,"owner_avatar_url":78,"owner_bio":79,"owner_company":80,"owner_location":80,"owner_email":80,"owner_twitter":81,"owner_website":82,"owner_url":83,"languages":84,"stars":97,"forks":98,"last_commit_at":99,"license":100,"difficulty_score":23,"env_os":101,"env_gpu":102,"env_ram":102,"env_deps":103,"category_tags":111,"github_topics":80,"view_count":23,"oss_zip_url":80,"oss_zip_packed_at":80,"status":16,"created_at":112,"updated_at":113,"faqs":114,"releases":115},2472,"featureform\u002Fenrichmcp","enrichmcp","EnrichMCP is a python framework for building data driven MCP servers","EnrichMCP 是一个专为构建数据驱动型 MCP（模型上下文协议）服务器设计的 Python 框架，被誉为“AI 代理的 ORM”。它的核心使命是帮助 AI 智能体更轻松地理解、导航和操作复杂的企业数据。\n\n在传统开发中，让 AI 准确访问数据库或 API 往往需要编写大量繁琐的适配代码，且容易出错。EnrichMCP 通过引入语义层，自动将现有的数据模型转化为类型安全、可被 AI 发现的标准化工具。这意味着开发者无需手动定义每个查询接口，AI 即可像人类一样理解数据结构，自动处理实体间的关联（如用户与订单的关系），并执行精准的数据检索。\n\nEnrichMCP 特别适合后端开发者、AI 应用工程师以及希望快速集成数据能力的技术团队。如果你正在使用 SQLAlchemy 管理数据库，只需几行代码即可将现有模型转换为 AI 友好的 API；若依赖 REST API，它也能快速封装并提供语义化支持。其技术亮点在于深度整合了 Pydantic 进行严格的输入输出验证，确保交互的稳定性，同时支持灵活的后台扩展，兼容各类数据库、API 或自定义逻辑。\n\n通过 EnrichMCP，你可以大幅降低","EnrichMCP 是一个专为构建数据驱动型 MCP（模型上下文协议）服务器设计的 Python 框架，被誉为“AI 代理的 ORM”。它的核心使命是帮助 AI 智能体更轻松地理解、导航和操作复杂的企业数据。\n\n在传统开发中，让 AI 准确访问数据库或 API 往往需要编写大量繁琐的适配代码，且容易出错。EnrichMCP 通过引入语义层，自动将现有的数据模型转化为类型安全、可被 AI 发现的标准化工具。这意味着开发者无需手动定义每个查询接口，AI 即可像人类一样理解数据结构，自动处理实体间的关联（如用户与订单的关系），并执行精准的数据检索。\n\nEnrichMCP 特别适合后端开发者、AI 应用工程师以及希望快速集成数据能力的技术团队。如果你正在使用 SQLAlchemy 管理数据库，只需几行代码即可将现有模型转换为 AI 友好的 API；若依赖 REST API，它也能快速封装并提供语义化支持。其技术亮点在于深度整合了 Pydantic 进行严格的输入输出验证，确保交互的稳定性，同时支持灵活的后台扩展，兼容各类数据库、API 或自定义逻辑。\n\n通过 EnrichMCP，你可以大幅降低构建智能数据接口的门槛，让 AI 代理真正具备“读懂”业务数据的能力，从而专注于更高价值的逻辑开发，而非底层数据连接的琐碎细节。","# EnrichMCP\n\n**The ORM for AI Agents - Turn your data model into a semantic MCP layer**\n\n[![CI](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Coverage](https:\u002F\u002Fcodecov.io\u002Fgh\u002Ffeatureform\u002Fenrichmcp\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Ffeatureform\u002Fenrichmcp)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fenrichmcp.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fenrichmcp\u002F)\n[![Python 3.11+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg)](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Fblob\u002Fmain\u002FLICENSE)\n[![Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-website-blue.svg)](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp)\n\nEnrichMCP is a Python framework that helps AI agents understand and navigate your data. Built on MCP (Model Context Protocol), it adds a semantic layer that turns your data model into typed, discoverable tools - like an ORM for AI.\n\n## What is EnrichMCP?\n\nThink of it as SQLAlchemy for AI agents. EnrichMCP automatically:\n\n- **Generates typed tools** from your data models\n- **Handles relationships** between entities (users → orders → products)\n- **Provides schema discovery** so AI agents understand your data structure\n- **Validates all inputs\u002Foutputs** with Pydantic models\n- **Works with any backend** - databases, APIs, or custom logic\n\n## Installation\n\n```bash\npip install enrichmcp\n\n# With SQLAlchemy support\npip install enrichmcp[sqlalchemy]\n```\n\n## Show Me Code\n\n### Option 1: I Have SQLAlchemy Models (30 seconds)\n\nTransform your existing SQLAlchemy models into an AI-navigable API:\n\n\n```python\nfrom enrichmcp import EnrichMCP\nfrom enrichmcp.sqlalchemy import (\n    include_sqlalchemy_models,\n    sqlalchemy_lifespan,\n    EnrichSQLAlchemyMixin,\n)\nfrom sqlalchemy import ForeignKey\nfrom sqlalchemy.ext.asyncio import create_async_engine\nfrom sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship\n\nengine = create_async_engine(\"postgresql+asyncpg:\u002F\u002Fuser:pass@localhost\u002Fdb\")\n\n\n# Add the mixin to your declarative base\nclass Base(DeclarativeBase, EnrichSQLAlchemyMixin):\n    pass\n\n\nclass User(Base):\n    \"\"\"User account.\"\"\"\n\n    __tablename__ = \"users\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"Unique user ID\"})\n    email: Mapped[str] = mapped_column(unique=True, info={\"description\": \"Email address\"})\n    status: Mapped[str] = mapped_column(default=\"active\", info={\"description\": \"Account status\"})\n    orders: Mapped[list[\"Order\"]] = relationship(\n        back_populates=\"user\", info={\"description\": \"All orders for this user\"}\n    )\n\n\nclass Order(Base):\n    \"\"\"Customer order.\"\"\"\n\n    __tablename__ = \"orders\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"Order ID\"})\n    user_id: Mapped[int] = mapped_column(\n        ForeignKey(\"users.id\"), info={\"description\": \"Owner user ID\"}\n    )\n    total: Mapped[float] = mapped_column(info={\"description\": \"Order total\"})\n    user: Mapped[User] = relationship(\n        back_populates=\"orders\", info={\"description\": \"User who placed the order\"}\n    )\n\n\n# That's it! Create your MCP app\napp = EnrichMCP(\n    \"E-commerce Data\",\n    \"API generated from SQLAlchemy models\",\n    lifespan=sqlalchemy_lifespan(Base, engine, cleanup_db_file=True),\n)\ninclude_sqlalchemy_models(app, Base)\n\nif __name__ == \"__main__\":\n    app.run()\n```\nAI agents can now:\n- `explore_data_model()` - understand your entire schema\n- `list_users(status='active')` - query with filters\n- `get_user(id=123)` - fetch specific records\n- Navigate relationships: `user.orders` → `order.user`\n\n### Option 2: I Have REST APIs (2 minutes)\n\nWrap your existing APIs with semantic understanding:\n\n```python\nfrom typing import Literal\nfrom enrichmcp import EnrichMCP, EnrichModel, Relationship\nfrom pydantic import Field\nimport httpx\n\napp = EnrichMCP(\"API Gateway\", \"Wrapper around existing REST APIs\")\nhttp = httpx.AsyncClient(base_url=\"https:\u002F\u002Fapi.example.com\")\n\n\n@app.entity()\nclass Customer(EnrichModel):\n    \"\"\"Customer in our CRM system.\"\"\"\n\n    id: int = Field(description=\"Unique customer ID\")\n    email: str = Field(description=\"Primary contact email\")\n    tier: Literal[\"free\", \"pro\", \"enterprise\"] = Field(description=\"Subscription tier\")\n\n    # Define navigable relationships\n    orders: list[\"Order\"] = Relationship(description=\"Customer's purchase history\")\n\n\n@app.entity()\nclass Order(EnrichModel):\n    \"\"\"Customer order from our e-commerce platform.\"\"\"\n\n    id: int = Field(description=\"Order ID\")\n    customer_id: int = Field(description=\"Associated customer\")\n    total: float = Field(description=\"Order total in USD\")\n    status: Literal[\"pending\", \"shipped\", \"delivered\"] = Field(description=\"Order status\")\n\n    customer: Customer = Relationship(description=\"Customer who placed this order\")\n\n\n# Define how to fetch data\n@app.retrieve()\nasync def get_customer(customer_id: int) -> Customer:\n    \"\"\"Fetch customer from CRM API.\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\")\n    return Customer(**response.json())\n\n\n# Define relationship resolvers\n@Customer.orders.resolver\nasync def get_customer_orders(customer_id: int) -> list[Order]:\n    \"\"\"Fetch orders for a customer.\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\u002Forders\")\n    return [Order(**order) for order in response.json()]\n\n\n@Order.customer.resolver\nasync def get_order_customer(order_id: int) -> Customer:\n    \"\"\"Fetch the customer for an order.\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Forders\u002F{order_id}\u002Fcustomer\")\n    return Customer(**response.json())\n\n\napp.run()\n```\n\n### Option 3: I Want Full Control (5 minutes)\n\nBuild a complete data layer with custom logic:\n\n```python\nfrom enrichmcp import EnrichMCP, EnrichModel, Relationship\nfrom datetime import datetime\nfrom decimal import Decimal\nfrom pydantic import Field\n\napp = EnrichMCP(\"Analytics Platform\", \"Custom analytics API\")\n\ndb = ...  # your database connection\n\n\n@app.entity()\nclass User(EnrichModel):\n    \"\"\"User with computed analytics fields.\"\"\"\n\n    id: int = Field(description=\"User ID\")\n    email: str = Field(description=\"Contact email\")\n    created_at: datetime = Field(description=\"Registration date\")\n\n    # Computed fields\n    lifetime_value: Decimal = Field(description=\"Total revenue from user\")\n    churn_risk: float = Field(description=\"ML-predicted churn probability 0-1\")\n\n    # Relationships\n    orders: list[\"Order\"] = Relationship(description=\"Purchase history\")\n    segments: list[\"Segment\"] = Relationship(description=\"Marketing segments\")\n\n\n@app.entity()\nclass Segment(EnrichModel):\n    \"\"\"Dynamic user segment for marketing.\"\"\"\n\n    name: str = Field(description=\"Segment name\")\n    criteria: dict = Field(description=\"Segment criteria\")\n    users: list[User] = Relationship(description=\"Users in this segment\")\n\n\n@app.entity()\nclass Order(EnrichModel):\n    \"\"\"Simplified order record.\"\"\"\n\n    id: int = Field(description=\"Order ID\")\n    user_id: int = Field(description=\"Owner user ID\")\n    total: Decimal = Field(description=\"Order total\")\n\n\n@User.orders.resolver\nasync def list_user_orders(user_id: int) -> list[Order]:\n    \"\"\"Fetch orders for a user.\"\"\"\n    rows = await db.query(\n        \"SELECT * FROM orders WHERE user_id = ? ORDER BY id DESC\",\n        user_id,\n    )\n    return [Order(**row) for row in rows]\n\n\n@User.segments.resolver\nasync def list_user_segments(user_id: int) -> list[Segment]:\n    \"\"\"Fetch segments that include the user.\"\"\"\n    rows = await db.query(\n        \"SELECT s.* FROM segments s JOIN user_segments us ON s.name = us.segment_name WHERE us.user_id = ?\",\n        user_id,\n    )\n    return [Segment(**row) for row in rows]\n\n\n@Segment.users.resolver\nasync def list_segment_users(name: str) -> list[User]:\n    \"\"\"List users in a segment.\"\"\"\n    rows = await db.query(\n        \"SELECT u.* FROM users u JOIN user_segments us ON u.id = us.user_id WHERE us.segment_name = ?\",\n        name,\n    )\n    return [User(**row) for row in rows]\n\n\n# Complex resource with business logic\n@app.retrieve()\nasync def find_high_value_at_risk_users(\n    lifetime_value_min: Decimal = 1000, churn_risk_min: float = 0.7, limit: int = 100\n) -> list[User]:\n    \"\"\"Find valuable customers likely to churn.\"\"\"\n    users = await db.query(\n        \"\"\"\n        SELECT * FROM users\n        WHERE lifetime_value >= ? AND churn_risk >= ?\n        ORDER BY lifetime_value DESC\n        LIMIT ?\n        \"\"\",\n        lifetime_value_min,\n        churn_risk_min,\n        limit,\n    )\n    return [User(**u) for u in users]\n\n\n# Async computed field resolver\n@User.lifetime_value.resolver\nasync def calculate_lifetime_value(user_id: int) -> Decimal:\n    \"\"\"Calculate total revenue from user's orders.\"\"\"\n    total = await db.query_single(\"SELECT SUM(total) FROM orders WHERE user_id = ?\", user_id)\n    return Decimal(str(total or 0))\n\n\n# ML-powered field\n@User.churn_risk.resolver\nasync def predict_churn_risk(user_id: int) -> float:\n    \"\"\"Run churn prediction model.\"\"\"\n    ctx = app.get_context()\n    features = await gather_user_features(user_id)\n    model = ctx.get(\"ml_models\")[\"churn\"]\n    return float(model.predict_proba(features)[0][1])\n\n\napp.run()\n```\n\n## Key Features\n\n### 🔍 Automatic Schema Discovery\n\nAI agents explore your entire data model with one call:\n\n```python\nschema = await explore_data_model()\n# Returns complete schema with entities, fields, types, and relationships\n```\n\n### 🔗 Relationship Navigation\n\nDefine relationships once, AI agents traverse naturally:\n\n```python\n# AI can navigate: user → orders → products → categories\nuser = await get_user(123)\norders = await user.orders()  # Automatic resolver\nproducts = await orders[0].products()\n```\n\n### 🛡️ Type Safety & Validation\n\nFull Pydantic validation on every interaction:\n\n```python\n@app.entity()\nclass Order(EnrichModel):\n    total: float = Field(ge=0, description=\"Must be positive\")\n    email: EmailStr = Field(description=\"Customer email\")\n    status: Literal[\"pending\", \"shipped\", \"delivered\"]\n```\n`describe_model()` will list these allowed values so agents know the valid options.\n\n### ✏️ Mutability & CRUD\n\nFields are immutable by default. Mark them as mutable and use\nauto-generated patch models for updates:\n\n```python\n@app.entity()\nclass Customer(EnrichModel):\n    id: int = Field(description=\"ID\")\n    email: str = Field(json_schema_extra={\"mutable\": True}, description=\"Email\")\n\n\n@app.create()\nasync def create_customer(email: str) -> Customer: ...\n\n\n@app.update()\nasync def update_customer(cid: int, patch: Customer.PatchModel) -> Customer: ...\n\n\n@app.delete()\nasync def delete_customer(cid: int) -> bool: ...\n```\n\n### 📄 Pagination Built-in\n\nHandle large datasets elegantly:\n\n```python\nfrom enrichmcp import PageResult\n\n\n@app.retrieve()\nasync def list_orders(page: int = 1, page_size: int = 50) -> PageResult[Order]:\n    orders, total = await db.get_orders_page(page, page_size)\n    return PageResult.create(items=orders, page=page, page_size=page_size, total_items=total)\n```\n\nSee the [Pagination Guide](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fpagination) for more examples.\n\n### 🔐 Context & Authentication\n\nPass auth, database connections, or any context:\n\n```python\nfrom pydantic import Field\nfrom enrichmcp import EnrichModel\n\n\nclass UserProfile(EnrichModel):\n    \"\"\"User profile information.\"\"\"\n\n    user_id: int = Field(description=\"User ID\")\n    bio: str | None = Field(default=None, description=\"Short bio\")\n\n\n@app.retrieve()\nasync def get_user_profile(user_id: int) -> UserProfile:\n    ctx = app.get_context()\n    # Access context provided by MCP client\n    auth_user = ctx.get(\"authenticated_user_id\")\n    if auth_user != user_id:\n        raise PermissionError(\"Can only access your own profile\")\n    return await db.get_profile(user_id)\n```\n\n### ⚡ Request Caching\n\nReduce API overhead by storing results in a per-request, per-user, or global cache:\n\n```python\n@app.retrieve()\nasync def get_customer(cid: int) -> Customer:\n    ctx = app.get_context()\n\n    async def fetch() -> Customer:\n        return await db.get_customer(cid)\n\n    return await ctx.cache.get_or_set(f\"customer:{cid}\", fetch)\n```\n\n### 🧭 Parameter Hints\n\nProvide examples and metadata for tool parameters using `EnrichParameter`:\n\n```python\nfrom enrichmcp import EnrichParameter\n\n\n@app.retrieve()\nasync def greet_user(name: str = EnrichParameter(description=\"user name\", examples=[\"bob\"])) -> str:\n    return f\"Hello {name}\"\n```\n\nTool descriptions will include the parameter type, description, and examples.\n\n### 🌐 HTTP & SSE Support\n\nServe your API over standard output (default), SSE, or HTTP:\n\n```python\napp.run()  # stdio default\napp.run(transport=\"streamable-http\")\n```\n\n## Why EnrichMCP?\n\nEnrichMCP adds three critical layers on top of MCP:\n\n1. **Semantic Layer** - AI agents understand what your data means, not just its structure\n2. **Data Layer** - Type-safe models with validation and relationships\n3. **Control Layer** - Authentication, pagination, and business logic\n\nThe result: AI agents can work with your data as naturally as a developer using an ORM.\n\n## Server-Side LLM Sampling\n\nEnrichMCP can request language model completions through MCP's **sampling**\nfeature. Call `ctx.ask_llm()` or the `ctx.sampling()` alias from any resource\nand the connected client will choose an LLM and pay for the usage. You can tune\nbehavior using options like `model_preferences`, `allow_tools`, and\n`max_tokens`. See [docs\u002Fserver_side_llm.md](docs\u002Fserver_side_llm.md) for more\ndetails.\n\n## Examples\n\nCheck out the [examples directory](examples\u002FREADME.md):\n\n- [hello_world](examples\u002Fhello_world) - The smallest possible EnrichMCP app\n- [hello_world_http](examples\u002Fhello_world_http) - HTTP example using streamable HTTP\n- [shop_api](examples\u002Fshop_api) - In-memory shop API with pagination and filters\n- [shop_api_sqlite](examples\u002Fshop_api_sqlite) - SQLite-backed version\n- [shop_api_gateway](examples\u002Fshop_api_gateway) - EnrichMCP as a gateway in front of FastAPI\n- [sqlalchemy_shop](examples\u002Fsqlalchemy_shop) - Auto-generated API from SQLAlchemy models\n- [mutable_crud](examples\u002Fmutable_crud) - Demonstrates mutable fields and CRUD decorators\n- [caching](examples\u002Fcaching) - Demonstrates ContextCache usage\n- [basic_memory](examples\u002Fbasic_memory) - Simple note-taking API using FileMemoryStore\n- [openai_chat_agent](examples\u002Fopenai_chat_agent) - Interactive chat client for MCP examples\n\n## Documentation\n\n- 📖 [Full Documentation](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp)\n- 🚀 [Getting Started Guide](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fgetting-started)\n- 🔧 [API Reference](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fapi)\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n## Development Setup\n\nThe repository requires **Python 3.11** or newer. The Makefile includes\ncommands to create a virtual environment and run the tests:\n\n```bash\nmake setup            # create .venv and install dependencies\nsource .venv\u002Fbin\u002Factivate\nmake test             # run the test suite\n```\n\nThis installs all development extras and pre-commit hooks so commands like\n`make lint` or `make docs` work right away.\n\n## License\n\nApache 2.0 - See [LICENSE](LICENSE)\n\n---\n\nBuilt by [Featureform](https:\u002F\u002Ffeatureform.com) • [MCP Protocol](https:\u002F\u002Fmodelcontextprotocol.io)\n","# EnrichMCP\n\n**面向AI代理的ORM——将您的数据模型转化为语义化的MCP层**\n\n[![CI](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Factions\u002Fworkflows\u002Fci.yml)\n[![Coverage](https:\u002F\u002Fcodecov.io\u002Fgh\u002Ffeatureform\u002Fenrichmcp\u002Fbranch\u002Fmain\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Ffeatureform\u002Fenrichmcp)\n[![PyPI](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fenrichmcp.svg)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fenrichmcp\u002F)\n[![Python 3.11+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11+-blue.svg)](https:\u002F\u002Fwww.python.org\u002Fdownloads\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-Apache%202.0-blue.svg)](https:\u002F\u002Fgithub.com\u002Ffeatureform\u002Fenrichmcp\u002Fblob\u002Fmain\u002FLICENSE)\n[![Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-website-blue.svg)](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp)\n\nEnrichMCP是一个Python框架，旨在帮助AI代理理解和导航您的数据。它基于MCP（模型上下文协议）构建，通过添加一个语义层，将您的数据模型转化为类型化、可发现的工具——就像AI领域的ORM一样。\n\n## 什么是EnrichMCP？\n\n您可以将其视为AI代理的SQLAlchemy。EnrichMCP会自动：\n\n- **从您的数据模型生成类型化工具**\n- **处理实体之间的关系**（用户 → 订单 → 产品）\n- **提供模式发现功能**，使AI代理能够理解您的数据结构\n- **使用Pydantic模型验证所有输入和输出**\n- **兼容任何后端**——数据库、API或自定义逻辑\n\n## 安装\n\n```bash\npip install enrichmcp\n\n# 如果需要SQLAlchemy支持\npip install enrichmcp[sqlalchemy]\n```\n\n## 示例代码\n\n### 方法一：已有SQLAlchemy模型（30秒）\n\n将您现有的SQLAlchemy模型转换为可被AI代理导航的API：\n\n\n```python\nfrom enrichmcp import EnrichMCP\nfrom enrichmcp.sqlalchemy import (\n    include_sqlalchemy_models,\n    sqlalchemy_lifespan,\n    EnrichSQLAlchemyMixin,\n)\nfrom sqlalchemy import ForeignKey\nfrom sqlalchemy.ext.asyncio import create_async_engine\nfrom sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship\n\nengine = create_async_engine(\"postgresql+asyncpg:\u002F\u002Fuser:pass@localhost\u002Fdb\")\n\n\n# 将混入类添加到您的声明式基类中\nclass Base(DeclarativeBase, EnrichSQLAlchemyMixin):\n    pass\n\n\nclass User(Base):\n    \"\"\"用户账户。\"\"\"\n\n    __tablename__ = \"users\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"唯一用户ID\"})\n    email: Mapped[str] = mapped_column(unique=True, info={\"description\": \"电子邮件地址\"})\n    status: Mapped[str] = mapped_column(default=\"active\", info={\"description\": \"账户状态\"})\n    orders: Mapped[list[\"Order\"]] = relationship(\n        back_populates=\"user\", info={\"description\": \"该用户的全部订单\"}\n    )\n\n\nclass Order(Base):\n    \"\"\"客户订单。\"\"\"\n\n    __tablename__ = \"orders\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"订单ID\"})\n    user_id: Mapped[int] = mapped_column(\n        ForeignKey(\"users.id\"), info={\"description\": \"下单用户ID\"}\n    )\n    total: Mapped[float] = mapped_column(info={\"description\": \"订单总额\"})\n    user: Mapped[User] = relationship(\n        back_populates=\"orders\", info={\"description\": \"下单用户\"}\n    )\n\n\n# 就这样！创建您的MCP应用\napp = EnrichMCP(\n    \"电子商务数据\",\n    \"由SQLAlchemy模型生成的API\",\n    lifespan=sqlalchemy_lifespan(Base, engine, cleanup_db_file=True),\n)\ninclude_sqlalchemy_models(app, Base)\n\nif __name__ == \"__main__\":\n    app.run()\n```\n现在，AI代理可以：\n- `explore_data_model()` - 理解您的整个模式\n- `list_users(status='active')` - 使用过滤条件查询\n- `get_user(id=123)` - 获取特定记录\n- 导航关系：`user.orders` → `order.user`\n\n### 方法二：已有REST API（2分钟）\n\n用语义理解包装您现有的API：\n\n```python\nfrom typing import Literal\nfrom enrichmcp import EnrichMCP, EnrichModel, Relationship\nfrom pydantic import Field\nimport httpx\n\napp = EnrichMCP(\"API网关\", \"现有REST API的封装层\")\nhttp = httpx.AsyncClient(base_url=\"https:\u002F\u002Fapi.example.com\")\n\n\n@app.entity()\nclass Customer(EnrichModel):\n    \"\"\"我们CRM系统中的客户。\"\"\"\n\n    id: int = Field(description=\"唯一客户ID\")\n    email: str = Field(description=\"主要联系邮箱\")\n    tier: Literal[\"free\", \"pro\", \"enterprise\"] = Field(description=\"订阅层级\")\n\n    # 定义可导航的关系\n    orders: list[\"Order\"] = Relationship(description=\"客户的购买历史\")\n\n\n@app.entity()\nclass Order(EnrichModel):\n    \"\"\"我们电商平台上的客户订单。\"\"\"\n\n    id: int = Field(description=\"订单ID\")\n    customer_id: int = Field(description=\"关联客户\")\n    total: float = Field(description=\"订单总金额，单位为美元\")\n    status: Literal[\"pending\", \"shipped\", \"delivered\"] = Field(description=\"订单状态\")\n\n    customer: Customer = Relationship(description=\"下单客户\")\n\n\n# 定义如何获取数据\n@app.retrieve()\nasync def get_customer(customer_id: int) -> Customer:\n    \"\"\"从CRM API获取客户信息。\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\")\n    return Customer(**response.json())\n\n\n# 定义关系解析器\n@Customer.orders.resolver\nasync def get_customer_orders(customer_id: int) -> list[Order]:\n    \"\"\"获取某客户的全部订单。\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\u002Forders\")\n    return [Order(**order) for order in response.json()]\n\n\n@Order.customer.resolver\nasync def get_order_customer(order_id: int) -> Customer:\n    \"\"\"获取订单对应的客户信息。\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Forders\u002F{order_id}\u002Fcustomer\")\n    return Customer(**response.json())\n\n\napp.run()\n```\n\n### 选项 3: 완전한 제어를 원합니다 (5분)\n\n사용자 정의 로직을 갖춘 완전한 데이터 계층을 구축하세요:\n\n```python\nfrom enrichmcp import EnrichMCP, EnrichModel, Relationship\nfrom datetime import datetime\nfrom decimal import Decimal\nfrom pydantic import Field\n\napp = EnrichMCP(\"Analytics Platform\", \"Custom analytics API\")\n\ndb = ...  # 귀하의 데이터베이스 연결\n\n\n@app.entity()\nclass User(EnrichModel):\n    \"\"\"계산된 분석 필드를 가진 사용자.\"\"\"\n\n    id: int = Field(description=\"사용자 ID\")\n    email: str = Field(description=\"연락 이메일\")\n    created_at: datetime = Field(description=\"가입 날짜\")\n\n    # 계산 필드\n    lifetime_value: Decimal = Field(description=\"사용자로부터의 총 수익\")\n    churn_risk: float = Field(description=\"ML로 예측된 이탈 확률 0-1\")\n\n    # 관계\n    orders: list[\"Order\"] = Relationship(description=\"구매 내역\")\n    segments: list[\"Segment\"] = Relationship(description=\"마케팅 세그먼트\")\n\n\n@app.entity()\nclass Segment(EnrichModel):\n    \"\"\"마케팅을 위한 동적 사용자 세그먼트.\"\"\"\n\n    name: str = Field(description=\"세그먼트 이름\")\n    criteria: dict = Field(description=\"세그먼트 기준\")\n    users: list[User] = Relationship(description=\"이 세그먼트에 속한 사용자들\")\n\n\n@app.entity()\nclass Order(EnrichModel):\n    \"\"\"간략화된 주문 기록.\"\"\"\n\n    id: int = Field(description=\"주문 ID\")\n    user_id: int = Field(description=\"소유자 사용자 ID\")\n    total: Decimal = Field(description=\"주문 총액\")\n\n\n@User.orders.resolver\nasync def list_user_orders(user_id: int) -> list[Order]:\n    \"\"\"사용자의 주문을 가져옵니다.\"\"\"\n    rows = await db.query(\n        \"SELECT * FROM orders WHERE user_id = ? ORDER BY id DESC\",\n        user_id,\n    )\n    return [Order(**row) for row in rows]\n\n\n@User.segments.resolver\nasync def list_user_segments(user_id: int) -> list[Segment]:\n    \"\"\"해당 사용자가 포함된 세그먼트를 가져옵니다.\"\"\"\n    rows = await db.query(\n        \"SELECT s.* FROM segments s JOIN user_segments us ON s.name = us.segment_name WHERE us.user_id = ?\",\n        user_id,\n    )\n    return [Segment(**row) for row in rows]\n\n\n@Segment.users.resolver\nasync def list_segment_users(name: str) -> list[User]:\n    \"\"\"세그먼트에 속한 사용자들을 나열합니다.\"\"\"\n    rows = await db.query(\n        \"SELECT u.* FROM users u JOIN user_segments us ON u.id = us.user_id WHERE us.segment_name = ?\",\n        name,\n    )\n    return [User(**row) for row in rows]\n\n\n# 비즈니스 로직이 포함된 복잡한 리소스\n@app.retrieve()\nasync def find_high_value_at_risk_users(\n    lifetime_value_min: Decimal = 1000, churn_risk_min: float = 0.7, limit: int = 100\n) -> list[User]:\n    \"\"\"이탈 가능성이 높은 고가치 고객을 찾습니다.\"\"\"\n    users = await db.query(\n        \"\"\"\n        SELECT * FROM users\n        WHERE lifetime_value >= ? AND churn_risk >= ?\n        ORDER BY lifetime_value DESC\n        LIMIT ?\n        \"\"\",\n        lifetime_value_min,\n        churn_risk_min,\n        limit,\n    )\n    return [User(**u) for u in users]\n\n\n# 비동기 계산 필드 리졸버\n@User.lifetime_value.resolver\nasync def calculate_lifetime_value(user_id: int) -> Decimal:\n    \"\"\"사용자의 주문에서 발생한 총 수익을 계산합니다.\"\"\"\n    total = await db.query_single(\"SELECT SUM(total) FROM orders WHERE user_id = ?\", user_id)\n    return Decimal(str(total or 0))\n\n\n# ML 기반 필드\n@User.churn_risk.resolver\nasync def predict_churn_risk(user_id: int) -> float:\n    \"\"\"이탈 예측 모델을 실행합니다.\"\"\"\n    ctx = app.get_context()\n    features = await gather_user_features(user_id)\n    model = ctx.get(\"ml_models\")[\"churn\"]\n    return float(model.predict_proba(features)[0][1])\n```\n\n## 주요 기능\n\n### 🔍 자동 스키마 탐색\n\nAI 에이전트는 단 한 번의 호출로 전체 데이터 모델을 탐색합니다:\n\n```python\nschema = await explore_data_model()\n# 엔티티, 필드, 타입 및 관계를 포함한 전체 스키마 반환\n```\n\n### 🔗 관계 탐색\n\n관계를 한 번 정의하면 AI 에이전트가 자연스럽게 탐색합니다:\n\n```python\n# AI는 사용자 → 주문 → 제품 → 카테고리로 탐색할 수 있습니다\nuser = await get_user(123)\norders = await user.orders()  # 자동 리졸버\nproducts = await orders[0].products()\n```\n\n### 🛡️ 타입 안전성 및 유효성 검사\n\n모든 상호작용에서 Pydantic 유효성 검사를 완벽하게 수행합니다:\n\n```python\n@app.entity()\nclass Order(EnrichModel):\n    total: float = Field(ge=0, description=\"양수여야 함\")\n    email: EmailStr = Field(description=\"고객 이메일\")\n    status: Literal[\"pending\", \"shipped\", \"delivered\"]\n```\n`describe_model()`은 이러한 허용값을 나열하여 에이전트가 유효한 옵션을 알 수 있도록 합니다.\n\n### ✏️ 변경 가능성 및 CRUD\n\n필드는 기본적으로 불변입니다. 변경 가능하도록 표시하고 자동 생성된 패치 모델을 사용하여 업데이트하세요:\n\n```python\n@app.entity()\nclass Customer(EnrichModel):\n    id: int = Field(description=\"ID\")\n    email: str = Field(json_schema_extra={\"mutable\": True}, description=\"이메일\")\n\n\n@app.create()\nasync def create_customer(email: str) -> Customer: ...\n\n\n@app.update()\nasync def update_customer(cid: int, patch: Customer.PatchModel) -> Customer: ...\n\n\n@app.delete()\nasync def delete_customer(cid: int) -> bool: ...\n```\n\n### 📄 기본 제공되는 페이징\n\n대규모 데이터셋을 우아하게 처리하세요:\n\n```python\nfrom enrichmcp import PageResult\n\n\n@app.retrieve()\nasync def list_orders(page: int = 1, page_size: int = 50) -> PageResult[Order]:\n    orders, total = await db.get_orders_page(page, page_size)\n    return PageResult.create(items=orders, page=page, page_size=page_size, total_items=total)\n```\n\n더 많은 예제는 [페이징 가이드](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fpagination)를 참조하세요.\n\n### 🔐 컨텍스트 및 인증\n\n인증 정보, 데이터베이스 연결 또는 기타 컨텍스트를 전달하세요:\n\n```python\nfrom pydantic import Field\nfrom enrichmcp import EnrichModel\n\n\nclass UserProfile(EnrichModel):\n    \"\"\"사용자 프로필 정보.\"\"\"\n\n    user_id: int = Field(description=\"사용자 ID\")\n    bio: str | None = Field(default=None, description=\"짧은 자기 소개\")\n\n\n@app.retrieve()\nasync def get_user_profile(user_id: int) -> UserProfile:\n    ctx = app.get_context()\n    # MCP 클라이언트가 제공한 컨텍스트 접근\n    auth_user = ctx.get(\"authenticated_user_id\")\n    if auth_user != user_id:\n        raise PermissionError(\"본인의 프로필만 접근 가능합니다\")\n    return await db.get_profile(user_id)\n```\n\n### ⚡ 요청 캐싱\n\n요청별, 사용자별 또는 글로벌 캐시에 결과를 저장하여 API 오버헤드를 줄이세요:\n\n```python\n@app.retrieve()\nasync def get_customer(cid: int) -> Customer:\n    ctx = app.get_context()\n\n    async def fetch() -> Customer:\n        return await db.get_customer(cid)\n\n    return await ctx.cache.get_or_set(f\"customer:{cid}\", fetch)\n```\n\n### 🧭 파라미터 힌트\n\n`EnrichParameter`을 사용하여 도구 파라미터에 대한 예시와 메타데이터를 제공하세요:\n\n```python\nfrom enrichmcp import EnrichParameter\n\n\n@app.retrieve()\nasync def greet_user(name: str = EnrichParameter(description=\"사용자 이름\", examples=[\"bob\"])) -> str:\n    return f\"Hello {name}\"\n```\n\n도구 설명에는 파라미터 유형, 설명 및 예시가 포함됩니다.\n\n### 🌐 HTTP 和 SSE 支持\n\n可以通过标准输出（默认）、SSE 或 HTTP 提供您的 API：\n\n```python\napp.run()  # 标准输出默认\napp.run(transport=\"streamable-http\")\n```\n\n## 为什么选择 EnrichMCP？\n\nEnrichMCP 在 MCP 的基础上增加了三层关键功能：\n\n1. **语义层** - AI 代理不仅理解数据的结构，还能理解数据的实际含义\n2. **数据层** - 类型安全的模型，具备验证和关系管理功能\n3. **控制层** - 身份验证、分页和业务逻辑\n\n结果是：AI 代理可以像开发者使用 ORM 一样自然地操作您的数据。\n\n## 服务器端 LLM 采样\n\nEnrichMCP 可以通过 MCP 的 **sampling** 功能请求语言模型完成任务。在任何资源中调用 `ctx.ask_llm()` 或其别名 `ctx.sampling()`，连接的客户端就会选择一个 LLM 并支付相应的费用。您可以通过 `model_preferences`、`allow_tools` 和 `max_tokens` 等选项来调整行为。更多详细信息请参阅 [docs\u002Fserver_side_llm.md](docs\u002Fserver_side_llm.md)。\n\n## 示例\n\n请查看 [examples 目录](examples\u002FREADME.md)：\n\n- [hello_world](examples\u002Fhello_world) - 最小的 EnrichMCP 应用程序\n- [hello_world_http](examples\u002Fhello_world_http) - 使用可流式 HTTP 的 HTTP 示例\n- [shop_api](examples\u002Fshop_api) - 带有分页和筛选器的内存中商店 API\n- [shop_api_sqlite](examples\u002Fshop_api_sqlite) - 基于 SQLite 的版本\n- [shop_api_gateway](examples\u002Fshop_api_gateway) - 将 EnrichMCP 作为 FastAPI 前端网关\n- [sqlalchemy_shop](examples\u002Fsqlalchemy_shop) - 从 SQLAlchemy 模型自动生成的 API\n- [mutable_crud](examples\u002Fmutable_crud) - 展示可变字段和 CRUD 装饰器\n- [caching](examples\u002Fcaching) - 展示 ContextCache 的使用\n- [basic_memory](examples\u002Fbasic_memory) - 使用 FileMemoryStore 的简单笔记 API\n- [openai_chat_agent](examples\u002Fopenai_chat_agent) - MCP 示例的交互式聊天客户端\n\n## 文档\n\n- 📖 [完整文档](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp)\n- 🚀 [入门指南](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fgetting-started)\n- 🔧 [API 参考](https:\u002F\u002Ffeatureform.github.io\u002Fenrichmcp\u002Fapi)\n\n## 贡献\n\n我们欢迎贡献！详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。\n\n## 开发环境设置\n\n该仓库需要 **Python 3.11** 或更高版本。Makefile 包含创建虚拟环境和运行测试的命令：\n\n```bash\nmake setup            # 创建 .venv 并安装依赖\nsource .venv\u002Fbin\u002Factivate\nmake test             # 运行测试套件\n```\n\n这将安装所有开发所需的额外包和 pre-commit 钩子，以便 `make lint` 或 `make docs` 等命令可以直接使用。\n\n## 许可证\n\nApache 2.0 - 请参阅 [LICENSE](LICENSE)\n\n---\n\n由 [Featureform](https:\u002F\u002Ffeatureform.com) • [MCP 协议](https:\u002F\u002Fmodelcontextprotocol.io) 构建","# EnrichMCP 快速上手指南\n\nEnrichMCP 是一个 Python 框架，旨在帮助 AI Agent 理解和导航数据。它基于 MCP（Model Context Protocol），将你的数据模型转换为具有语义层的、类型安全的可发现工具，类似于 AI 领域的 ORM。\n\n## 环境准备\n\n*   **Python 版本**：需要 Python 3.11 或更高版本。\n*   **前置知识**：了解 Pydantic 模型定义及基本的异步编程概念有助于更好地使用高级功能。\n*   **依赖建议**：如果你计划连接关系型数据库，建议安装 SQLAlchemy 支持。\n\n## 安装步骤\n\n使用 pip 进行安装。根据你的需求选择以下命令之一：\n\n**基础安装：**\n```bash\npip install enrichmcp\n```\n\n**包含 SQLAlchemy 支持（推荐用于数据库集成）：**\n```bash\npip install enrichmcp[sqlalchemy]\n```\n\n> **提示**：如果下载速度较慢，可以使用国内镜像源加速，例如：\n> `pip install enrichmcp -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple`\n\n## 基本使用\n\nEnrichMCP 提供了多种集成方式。以下是两种最常见场景的快速入门示例。\n\n### 场景一：集成现有 SQLAlchemy 模型（最快上手）\n\n如果你已经拥有 SQLAlchemy 数据模型，只需少量代码即可将其转换为 AI 可导航的 API。\n\n```python\nfrom enrichmcp import EnrichMCP\nfrom enrichmcp.sqlalchemy import (\n    include_sqlalchemy_models,\n    sqlalchemy_lifespan,\n    EnrichSQLAlchemyMixin,\n)\nfrom sqlalchemy import ForeignKey\nfrom sqlalchemy.ext.asyncio import create_async_engine\nfrom sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship\n\n# 创建异步引擎\nengine = create_async_engine(\"postgresql+asyncpg:\u002F\u002Fuser:pass@localhost\u002Fdb\")\n\n# 将 Mixin 添加到声明基类中\nclass Base(DeclarativeBase, EnrichSQLAlchemyMixin):\n    pass\n\nclass User(Base):\n    \"\"\"用户账户\"\"\"\n    __tablename__ = \"users\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"唯一用户ID\"})\n    email: Mapped[str] = mapped_column(unique=True, info={\"description\": \"电子邮件地址\"})\n    status: Mapped[str] = mapped_column(default=\"active\", info={\"description\": \"账户状态\"})\n    orders: Mapped[list[\"Order\"]] = relationship(\n        back_populates=\"user\", info={\"description\": \"该用户的所有订单\"}\n    )\n\nclass Order(Base):\n    \"\"\"客户订单\"\"\"\n    __tablename__ = \"orders\"\n\n    id: Mapped[int] = mapped_column(primary_key=True, info={\"description\": \"订单ID\"})\n    user_id: Mapped[int] = mapped_column(\n        ForeignKey(\"users.id\"), info={\"description\": \"所属用户ID\"}\n    )\n    total: Mapped[float] = mapped_column(info={\"description\": \"订单总额\"})\n    user: Mapped[User] = relationship(\n        back_populates=\"orders\", info={\"description\": \"下单用户\"}\n    )\n\n# 创建 MCP 应用\napp = EnrichMCP(\n    \"电商数据\",\n    \"从 SQLAlchemy 模型生成的 API\",\n    lifespan=sqlalchemy_lifespan(Base, engine, cleanup_db_file=True),\n)\ninclude_sqlalchemy_models(app, Base)\n\nif __name__ == \"__main__\":\n    app.run()\n```\n\n**AI Agent 现在可以执行的操作：**\n*   `explore_data_model()`：理解整个数据结构。\n*   `list_users(status='active')`：带过滤条件的查询。\n*   `get_user(id=123)`：获取特定记录。\n*   自动导航关系：如通过 `user.orders` 访问订单。\n\n### 场景二：封装 REST API 或自定义逻辑\n\n如果没有 ORM，或者需要封装现有的 HTTP API，可以使用 `EnrichModel` 手动定义实体和解析器。\n\n```python\nfrom typing import Literal\nfrom enrichmcp import EnrichMCP, EnrichModel, Relationship\nfrom pydantic import Field\nimport httpx\n\napp = EnrichMCP(\"API 网关\", \"现有 REST API 的包装层\")\nhttp = httpx.AsyncClient(base_url=\"https:\u002F\u002Fapi.example.com\")\n\n@app.entity()\nclass Customer(EnrichModel):\n    \"\"\"CRM 系统中的客户\"\"\"\n    id: int = Field(description=\"唯一客户ID\")\n    email: str = Field(description=\"主要联系邮箱\")\n    tier: Literal[\"free\", \"pro\", \"enterprise\"] = Field(description=\"订阅层级\")\n    \n    # 定义可导航的关系\n    orders: list[\"Order\"] = Relationship(description=\"客户的购买历史\")\n\n@app.entity()\nclass Order(EnrichModel):\n    \"\"\"电商平台订单\"\"\"\n    id: int = Field(description=\"订单ID\")\n    customer_id: int = Field(description=\"关联客户\")\n    total: float = Field(description=\"订单总额（美元）\")\n    status: Literal[\"pending\", \"shipped\", \"delivered\"] = Field(description=\"订单状态\")\n    \n    customer: Customer = Relationship(description=\"下单客户\")\n\n# 定义数据获取方法\n@app.retrieve()\nasync def get_customer(customer_id: int) -> Customer:\n    \"\"\"从 CRM API 获取客户信息\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\")\n    return Customer(**response.json())\n\n# 定义关系解析器\n@Customer.orders.resolver\nasync def get_customer_orders(customer_id: int) -> list[Order]:\n    \"\"\"获取客户的订单列表\"\"\"\n    response = await http.get(f\"\u002Fapi\u002Fcustomers\u002F{customer_id}\u002Forders\")\n    return [Order(**order) for order in response.json()]\n\nif __name__ == \"__main__\":\n    app.run()\n```\n\n**核心特性说明：**\n*   **类型安全**：所有输入输出均通过 Pydantic 进行验证。\n*   **关系导航**：定义一次关系，AI 即可自然遍历（如 `customer.orders`）。\n*   **模式发现**：AI 可通过 `explore_data_model` 自动了解可用数据和字段含义。","某电商公司的数据工程师需要为内部 AI 客服助手提供实时访问用户订单和账户状态的能力，底层数据存储在 PostgreSQL 数据库中，且已使用 SQLAlchemy 定义了完善的数据模型。\n\n### 没有 enrichmcp 时\n\n- **重复开发成本高**：工程师必须手动编写大量 CRUD API 接口或 MCP 工具函数，将数据库查询逻辑逐一映射为 AI 可调用的工具，工作繁琐且易出错。\n- **上下文理解困难**：AI 代理无法自动感知“用户”与“订单”之间的外键关联，开发者需硬编码提示词来解释数据结构，导致 AI 在处理跨表查询（如“查找某用户的所有订单”）时经常出错。\n- **维护同步滞后**：当数据库 schema 发生变更（如新增字段）时，开发者需手动更新 API 定义、Pydantic 验证模型及 AI 提示词，极易出现代码与文档不一致的情况。\n- **缺乏类型安全**：手动构建的工具链缺乏严格的输入输出验证，AI 生成的错误参数常导致后端报错，调试过程耗时费力。\n\n### 使用 enrichmcp 后\n\n- **自动化生成工具**：只需在现有的 SQLAlchemy 模型上添加 `EnrichSQLAlchemyMixin` 并调用 `include_sqlalchemy_models`，enrichmcp 即可自动将数据模型转换为带类型的 MCP 工具，零样板代码。\n- **语义化关系导航**：enrichmcp 自动解析模型间的 `relationship`，AI 代理能自然理解并遍历“用户→订单”的关联路径，无需额外提示即可准确执行复杂关联查询。\n- **动态 Schema 发现**：AI 可通过 `explore_data_model` 实时获取最新的数据库结构，当底层表结构变更时，MCP 服务自动同步更新，确保 AI 始终基于最新元数据操作。\n- **内置数据验证**：基于 Pydantic 自动处理所有输入输出的类型校验，非法请求在入口处即被拦截，大幅提升了系统的稳定性和开发效率。\n\nenrichmcp 的核心价值在于像 ORM 简化数据库操作一样，通过自动化语义层将数据模型直接转化为 AI 可理解、可交互的标准工具，极大降低了数据驱动型 AI 应用的开发门槛。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ffeatureform_enrichmcp_40022000.png","featureform","Featureform","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ffeatureform_d6ce3a91.png","We turn features into first-class component of the ML process.",null,"FeatureformML","https:\u002F\u002Ffeatureform.com","https:\u002F\u002Fgithub.com\u002Ffeatureform",[85,89,93],{"name":86,"color":87,"percentage":88},"Python","#3572A5",98,{"name":90,"color":91,"percentage":92},"Makefile","#427819",1.6,{"name":94,"color":95,"percentage":96},"Shell","#89e051",0.4,644,33,"2026-04-02T19:39:52","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":104,"python":105,"dependencies":106},"该工具是一个基于 MCP (Model Context Protocol) 的 Python 框架，用于将数据模型转换为 AI 代理可理解的语义层。支持 SQLAlchemy 模型自动映射、REST API 封装以及自定义逻辑。安装时可根据需求选择基础版或带 SQLAlchemy 支持的版本 (pip install enrichmcp[sqlalchemy])。无特定 GPU 或高内存要求，主要依赖异步编程环境。","3.11+",[107,108,109,110],"pydantic","sqlalchemy","asyncpg","httpx",[13,15],"2026-03-27T02:49:30.150509","2026-04-06T05:36:24.576660",[],[116,121,126,131,136,141,146,151,156],{"id":117,"version":118,"summary_zh":119,"released_at":120},61890,"v0.4.7","### 新增\n- 通过 `ask_llm()` 实现服务器端 LLM 采样，并新增 `ask_user()` 辅助函数。\n- 提供 `prefer_medium_model()` 用于平衡的模型选择。\n- 扩展了示例和测试，包括 Redis 缓存和旅行规划器。\n### 变更\n- 移除了自动注入 `EnrichContext` 的功能；请使用 `app.get_context()`。\n- 改进了聊天代理和记忆示例。\n### 修复\n- 修正了示例中及 `ask_llm` 辅助函数中的上下文使用问题。","2025-07-14T20:17:14",{"id":122,"version":123,"summary_zh":124,"released_at":125},61891,"v0.4.6","### 新增\n- `EnrichParameter`：用于为资源参数添加描述和示例。\n- 内置数据模型探索工具返回的 `DataModelSummary` 对象。\n- 通过新的 `ToolDef` 和 `ToolKind` 辅助类，标准化工具描述。\n### 变更\n- 内置数据模型工具的描述现指示在会话开始时调用一次。\n- 改进了 `DataModelSummary` 的字符串格式化，以及探索端点的输出。\n### 修复\n- 修复了探索端点返回的字段描述的类型定义问题。","2025-07-10T10:20:51",{"id":127,"version":128,"summary_zh":129,"released_at":130},61892,"v0.4.5","### 新增\n- 使用 `MemoryCache` 和可选的 `RedisCache` 后端进行上下文缓存。\n- `EnrichMCP.get_context()` 返回一个 `EnrichContext` 实例，该实例镜像底层的 FastMCP 上下文。","2025-07-02T23:27:18",{"id":132,"version":133,"summary_zh":134,"released_at":135},61893,"v0.4.3","### 新增\n- 通过 `app.run(transport=\"streamable-http\")` 实现 HTTP 传输\n- 基本内存示例，演示 `FileMemoryStore`\n- hello_world 示例的 `mcp_use` 客户端\n### 变更\n- SQLAlchemy 关系解析器现在使用 `page` 和 `page_size` 参数返回 `PageResult`，且无需执行计数查询。\n### 修复\n- 修正了 HTTP 示例中的路径处理问题","2025-06-24T18:06:14",{"id":137,"version":138,"summary_zh":139,"released_at":140},61894,"v0.4.2","### 变更\n- 将 `app.resource` 装饰器重命名为 `app.retrieve`。`app.resource` 仍作为已弃用的别名保留。\n### 新增\n- 支持通过 `mutable=True` 标记字段为可变，并提供 CRUD 示例\n- 对 SQLAlchemy 集成中 BigInteger 列类型的处理\n- 示例冒烟测试及改进的 OpenAI 聊天示例\n- SQLAlchemy 生命周期的可选清理功能\n- 详细的 ROBOTS 指南及 CI 改进","2025-06-20T21:36:08",{"id":142,"version":143,"summary_zh":144,"released_at":145},61895,"v0.4.1","### 已修复\n- 确保自动生成的 SQLAlchemy 资源函数在注册前将 `ctx` 注解设置为 `EnrichContext`，以便 FastMCP 能将其识别为类。","2025-06-15T01:00:19",{"id":147,"version":148,"summary_zh":149,"released_at":150},61896,"v0.4.0","### 新增\n- 新增 `shop_api_gateway` 示例，展示如何将 EnrichMCP 用作 API 网关\n- SQLAlchemy 集成，包括 `EnrichSQLAlchemyMixin`、`include_sqlalchemy_models` 和 `sqlalchemy_lifespan`\n- 自动从 SQLAlchemy 模型生成资源和关系解析器\n- 示例项目 `examples\u002Fsqlalchemy_shop`\n### 变更\n- 开发环境现在使用 `uv`","2025-06-12T21:28:25",{"id":152,"version":153,"summary_zh":154,"released_at":155},61897,"v0.3.0","### 新增\n- 上下文支持\n- 生命周期支持\n- 分页","2025-06-11T21:25:43",{"id":157,"version":158,"summary_zh":159,"released_at":160},61898,"v0.2.0","发布版本 0.2.0","2025-05-29T01:36:14"]