AI导哈

AI代理模型上下文协议服务器

一个基于FastAPI和Python 3.11+构建的AI代理交互模型上下文协议（MCP）服务器实现，适用于AI代理的交互和模型管理。

  • by luminosita
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 luminosita/mcp

使用说明

AI代理MCP服务器

一个用于AI代理交互的模型上下文协议（MCP）服务器实现，基于FastAPI和Python 3.11+构建。

快速入门

先决条件

  • Python 3.11+
  • Podman
  • Git（注：Git是一个分布式版本控制系统，常用于软件开发中代码的版本管理）
  • NuShell（用于设置脚本）

设置

# Run automated setup script
nu scripts/setup.nu

# Or run in silent mode (CI/CD)
nu scripts/setup.nu --silent

发展

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate     # Windows

# Run development server
task dev

# Run tests
task test

# Run linting
task lint

项目结构

project-root/
├── src/mcp_server/          # Main application package
│   ├── core/                # Core utilities and exceptions
│   ├── models/              # Data models
│   ├── services/            # Business logic
│   ├── repositories/        # Data access layer
│   ├── tools/               # MCP tools
│   ├── api/                 # FastAPI routes and schemas
│   └── utils/               # Utility functions
├── tests/                   # Test suite
│   ├── unit/                # Unit tests
│   ├── integration/         # Integration tests
│   └── e2e/                 # End-to-end tests
├── scripts/                 # Setup and utility scripts
└── docs/                    # Documentation

部署

容器镜像会在所有分支上自动构建，并且仅在（特定条件下）推送到GitHub容器注册表 release/* 分支。所有容器镜像在部署前都会进行安全漏洞扫描。

安全扫描

所有容器构建都会使用Trivy自动进行漏洞扫描：

  • 范围： 操作系统包、Python依赖项和基础镜像中的CVE（通用漏洞与披露）
  • 严重性策略：
    • 关键/高： 阻止部署（构建失败）
    • 中/低： 记录为警告，部署继续
  • 未修复的漏洞： 被忽略（无法修复）
  • 扫描结果： 上传到GitHub安全选项卡以进行集中跟踪
  • 数据库更新： Trivy漏洞数据库每日更新
  • 已记录的异常： 已追踪进入 .trivyignore 进行风险评估

查看漏洞报告： 仓库 → 安全 → 代码扫描

已知问题（.trivyignore）：

  • CVE-2025-7709（libsqlite3-0）- 等待Debian安全更新
  • CVE-2025-8869（pip）- 等待Python基础镜像更新

发布流程

  1. 创建发布分支： git checkout -b release/v0.1.0
  2. 在（此处）更新版本 pyproject.toml
  3. 推送以触发自动化构建、安全扫描和推送： git push -u origin release/v0.1.0
  4. 安全扫描验证镜像（如果发现CRITICAL/HIGH级别的CVE，则阻止）
  5. 容器镜像自动推送到 ghcr.io （如果扫描通过）带有版本标签

使用预构建的镜像

# Pull latest image
podman pull ghcr.io/USERNAME/REPO:latest

# Pull specific version
podman pull ghcr.io/USERNAME/REPO:0.1.0

# Pull by commit SHA
podman pull ghcr.io/USERNAME/REPO:abc123def

# Run container
podman run -d -p 8000:8000 ghcr.io/USERNAME/REPO:latest

本地建设

# Build with Taskfile
task container:build

# Build with custom tag
TAG=custom task container:build

# Run locally built image
task container:run

文档

技术栈

  • FastAPI - 现代Python网络框架
  • Pydantic（注：这是一个库名，通常不直接翻译，保持原名） - 数据验证
  • 紫外线 - 快速的Python包管理器
  • 任务文件 - 任务自动化
  • Devbox - 独立的开发环境
  • Pytest（注：这是一个软件测试框架的名称，直接翻译为“Pytest”即可，无需额外解释其含义） - 测试框架
  • “Ruff”在中文中可以翻译为“粗糙”或“毛糙”，具体含义取决于上下文。如果是指表面或质地，可以理解为“粗糙的”；如果是指行为或态度，可能意味着“粗鲁的”或“不拘小节的”。但通常情况下，“Ruff”作为形容词时，主要翻译为“粗糙的” - 代码检查和格式化
  • MyPy - 静态类型检查

许可证

待定

相关 MCP