AI导哈

元数据代理服务

MCP元数据代理是一个基于FastAPI的服务，用于暴露元数据目录协议（MCP）描述符并将API消费者路由到正确的目录元数据，而无需规定完整的UI。

  • by nestharus
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 nestharus/mcp-to-skills

使用说明

MCP元数据代理

概述

MCP元数据代理将是一个FastAPI服务，它公开元数据目录协议（MCP）描述符，并将API消费者路由到正确的目录元数据，而无需规定完整的UI。它是自举的，因此早期阶段在路由和编排层固化之前捕获高级契约、配置和最终服务表面。

项目结构

  • app/：主要的FastAPI应用程序代码和域模型。
  • scripts/：支持未来阶段的辅助脚本（例如引导或操作工具）。
  • docs/：MCP行为、操作说明和过程指南的参考文件。
  • tests/：随着时间的推移，验证代理、其端点和集成的自动化测试。

技术栈

  • Python 3.14
  • 快速API
  • Uvicorn
  • Pydantic v2
  • Pydantic设置
  • orjson
  • tomllib（Python 3.11+标准库TOML解析器）
  • 紫外线
  • 雏鸟

开发状态

该项目正处于初始化阶段。核心工件，如 scripts/start-server.py 和那个 /api/metadata/v1/health 端点现在可用，即使更广泛的MCP元数据编排和缓存功能仍在开发中，您也可以使用配置的入口点。

项目设置

跑 uv sync 要安装依赖项，请执行以下操作 uv run mcp-setup 安装中定义的预提交挂钩 .pre-commit-config.yaml。如果缺少开发依赖组（预提交、pytest等），脚本会自动拉入，因此没有额外的 uv sync --group dev 步骤是必需的。这使得每次提交时Ruff格式和lint检查都与CI保持一致，同时保持明确的选择加入步骤。

发展（未来步骤）

  1. uv sync && uv run mcp-setup #安装deps和预提交挂钩。
  2. 集 MCP_CONFIG_PATH 指向你的 mcp.toml.
  3. 通过入口脚本运行代理(scripts/start-server.py)或通过 uvicorn app.main:app --reload.
  4. 使用 /api/metadata/v1/health 验证代理是否响应。

前提条件

  • 紫外线： pip install uv
  • Docker（可选，用于容器运行）
  • 预提交（通过开发依赖关系引入；请参阅上面的安装脚本）

构建

lock-deps（现在是可选的；一旦pylock.toml被提交，它就成为必需的）

紫外线锁

生成OpenAPI（写OpenAPI/OpenAPI.json）

uv运行gen_openapi--配置测试/夹具/sample_mcp.toml

在没有准备好的MCP配置的情况下生成OpenAPI（跳过配置存在性检查）

uv运行gen_openapi--允许缺少配置

使用 --allow-missing-config 跳过验证 MCP_CONFIG_PATH，允许您在提交实数之前创建模式 mcp.toml 文件。

代码质量

代码检查

运行组合的Ruff工作流（首先是格式化程序，其次是lint），以便及早发现样式或静态分析问题：

uv run lint

格式化

uv run lint 已运行 ruff format . 在lint步骤之前，保持导入的排序和格式在提交中保持一致。当您需要快速清理而不需要linting时，可以单独运行格式化：

uv run ruff format .

组合工作流程

提交前，运行 uv run lint 因此，格式化和linting是一起处理的。这样做在本地反映了下面描述的自动检查，并减少了CI流失。

CI集成

添加 uv run lint 因此，如果样式或lint回归出现，拉取请求将失败。因为Ruff已经在中配置 pyproject.toml，CI继承了开发人员在本地使用的相同规则集。

预提交钩子

安装项目的预提交挂钩，以便在创建提交时自动进行linting和格式化。挂钩自动安装通过 uv run mcp-setup；手动安装仍然可用：

uv run pre-commit install

要验证每个文件（对CI有用或在打开拉取请求之前），请运行：

uv run pre-commit run --all-files

钩子的定义见 .pre-commit-config.yaml 并使用项目中其他地方配置的相同Ruff版本，确保开发人员、本地自动化和CI之间的结果一致。

运行（本地）

uv运行uvicorn应用程序。main：应用程序--主机0.0.0.0--端口8000--重新加载 检查运行状况端点：

运行（Docker）

docker build-t mcp元数据代理：dev。 docker run--rm-p 8000:8000-e MCP_CONFIG_PATH=/configs/MCP.toml-v/PATH/to/MCP.toml:/configs/MCP.toml:ro MCP元数据代理：dev

贡献

  • 将所有测试置于 tests/ 遵循三层结构(unit/, integration/, component/)记录在 docs/TESTING_ARCHITECTURE.md在每一层内镜像运行时包结构（例如。， tests/unit/core/test_settings.py 为了 app/core/settings.py).中的pytest配置 pyproject.toml 已设置 testpaths = ["tests"] 用于自动发现。

相关 MCP