AI治理框架文档访问服务

FINOS AI治理MCP服务器

人工智能治理框架通过模型上下文协议记录访问。

该项目通过MCP从FINOS存储库直接访问AI治理框架文档，使其在Claude、VS Code、Cursor和其他支持的工具中可用。

快速开始

# Clone the repository
git clone https://github.com/finos/aigf-mcp-server.git
cd aigf-mcp-server

# Create and activate a virtual environment
python -m venv venv

# On Windows:
venv\Scripts\activate

# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -e .

# Required security setting (generate your own value; choose one)
export FINOS_MCP_CACHE_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
# OR
export FINOS_MCP_CACHE_SECRET=$(openssl rand -hex 32)

# Test
finos-mcp --help
mcp list tools

注： 使用虚拟环境将项目依赖关系与系统Python隔离开来，防止冲突并保持环境清洁。这是Python开发的推荐方法。

→ 完整设置指南 -连接到克劳德、VS代码、游标等。

Docker部署（本地+云）

此存储库现在包括：

• Dockerfile 用于制作风格的容器图像
• docker-compose.yml 用于本地部署

使用Docker Compose在本地运行

# 1) Create Docker env file
cp .env.docker.example .env.docker

# 2) Put a real 32+ char value in .env.docker
# FINOS_MCP_CACHE_SECRET=...

# 3) Start
docker compose up --build -d

# 4) Follow logs
docker compose logs -f finos-mcp-server

服务器终结点：

• http://localhost:8000/mcp

直接构建和运行映像

docker build -t finos-mcp-server:latest .

docker run --rm -p 8000:8000 \
  -e FINOS_MCP_CACHE_SECRET="$(openssl rand -hex 32)" \
  -e FINOS_MCP_MCP_TRANSPORT=http \
  -e FINOS_MCP_MCP_HOST=0.0.0.0 \
  -e FINOS_MCP_MCP_PORT=8000 \
  finos-mcp-server:latest

在AWS/GCP/Azure/Kubernetes中使用

在部署时使用相同的容器映像并传递环境变量：

• FINOS_MCP_CACHE_SECRET （必填，最少32个字符）
• FINOS_MCP_MCP_TRANSPORT=http
• FINOS_MCP_MCP_HOST=0.0.0.0
• FINOS_MCP_MCP_PORT （例如 8000)
• FINOS_MCP_GITHUB_TOKEN （推荐）
• 如果 FINOS_MCP_MCP_AUTH_ENABLED=true那么 FINOS_MCP_MCP_AUTH_ISSUER, FINOS_MCP_MCP_AUTH_AUDIENCE，其中之一 FINOS_MCP_MCP_AUTH_JWKS_URI 或 FINOS_MCP_MCP_AUTH_PUBLIC_KEY 也是必需的。

云映射示例：

• AWS ECS/Fargate：任务定义环境变量+密钥管理器 FINOS_MCP_CACHE_SECRET
• GCP云运行：容器环境变量+密钥管理器挂载/引用
• 库贝内特斯： Deployment 环境变量+ Secret 对于敏感值

可用的MCP工具

框架访问工具（5）

风险与缓解工具（4）

系统监控工具（2）

支持的内容

人工智能治理框架

• 框架定义是在运行时从配置的上游存储库中发现的。
• 使用 list_frameworks 查看可用于部署的当前目录。

风险和缓解类别

风险类别

缓解类别

常见用例

框架研究

• 列出可用框架：使用 list_frameworks 查看所有支持的治理框架
• 获取框架内容：使用 get_framework 检索完整的框架文档
• 搜索框架内容：使用 search_frameworks 在框架中查找特定文本

风险管理

• 浏览可用风险：使用 list_risks 查看所有记录在案的人工智能治理风险
• 获取风险详细信息：使用 get_risk 检索完整的风险文档
• 搜索风险：使用 search_risks 按关键字查找特定风险

缓解计划

• 浏览可用的缓解措施：使用 list_mitigations 查看所有记录在案的缓解策略
• 获取缓解详细信息：使用 get_mitigation 检索完整的缓解文档
• 搜索缓解措施：使用 search_mitigations 按关键字查找特定缓解措施

系统监控

• 健康状况：使用 get_service_health 监控系统可用性
• 性能指标：使用 get_cache_stats 监控缓存性能

建筑

组件

• FastMCP运行时引导 (src/finos_mcp/fastmcp_server.py)：FastMCP服务器构建、模型定义和工具注册接线
• API注册模块 (src/finos_mcp/api/)：专用工具/资源/快速注册和MCP有效载荷映射
• MCP工具：11个工具分为3类（框架访问、风险与缓解、系统监控）
• MCP提示：3个框架分析和风险评估的快速模板
• MCP资源：3种具有finos的资源类型：//用于结构化访问的URI方案
• 应用服务和用例 (src/finos_mcp/application/)：搜索文本解析、提示组合、可观察性投影和域流
• 内容管理 (src/finos_mcp/content/)：动态内容加载和缓存
• 安全层 (src/finos_mcp/security/)：请求验证和保护
• 运行时护栏 (src/finos_mcp/fastmcp_server.py)：基于中间件的速率限制、安全错误响应和有效载荷大小强制

设计原则

• 仅限文档访问：直接查阅治理框架文件
• 框架不可知：适用于任何治理框架文件结构
• 模块化工具系统：易于添加和移除工具
• 安全第一：所有请求都经过验证和保护
• 性能优化：智能缓存和异步操作

运行时安全控制

• 中间件订单：错误处理->定时->日志记录->速率限制
• 输入限制：工具、提示和资源参数强制执行最大长度和请求大小检查
• 输出限制：资源/文档有效载荷在返回给客户端之前经过大小验证
• 错误披露控制：外部错误被清理并标记相关性
• 故障信号策略：通过显式方式动态发现GitHub unavailable 无法访问上游内容时的响应
• 边界身份验证（可选）：在MCP边界与发行人/受众/范围执行进行JWT验证

发展

设置

# Install development dependencies
pip install -e ".[dev,security,test]"

# Run CI-equivalent checks locally
./scripts/ci-local.sh

# Run tests
pytest

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run fast tests
pytest -c pytest.fast.ini

# Test MCP server
mcp list tools

添加新工具

工具添加遵循分层运行时模式：

1. 在中添加有效载荷生成器或注册接线 src/finos_mcp/api/tools/
2. 在中添加或扩展用例逻辑 src/finos_mcp/application/use_cases/
3. 从以下位置注册MCP表面 src/finos_mcp/fastmcp_server.py
4. 在中添加或更新测试 tests/unit/ 必要时提供集成覆盖
5. 更新工具文档

配置

环境变量和配置：

• 从GitHub存储库动态加载的内容
• 中的缓存配置 src/finos_mcp/content/cache.py
• 中的安全设置 src/finos_mcp/security/

所需的安全配置

FINOS_MCP_CACHE_SECRET 启动时需要。

# Option 1 (Python)
export FINOS_MCP_CACHE_SECRET=$(python -c "import secrets; print(secrets.token_hex(32))")
# Option 2 (OpenSSL)
export FINOS_MCP_CACHE_SECRET=$(openssl rand -hex 32)

笔记：

• 为每个环境使用一个唯一的秘密。
• 不要把真正的秘密交给git。

MCP身份验证配置

使用JWT验证（FastMCP JWTVerifier)在生产中保护MCP边界。

export FINOS_MCP_MCP_AUTH_ENABLED=true
export FINOS_MCP_MCP_AUTH_ISSUER=https://auth.example.com
export FINOS_MCP_MCP_AUTH_AUDIENCE=finos-mcp-server
export FINOS_MCP_MCP_AUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.json
export FINOS_MCP_MCP_AUTH_REQUIRED_SCOPES=governance:read,governance:write

笔记：

• 精确设置以下之一 FINOS_MCP_MCP_AUTH_JWKS_URI 或 FINOS_MCP_MCP_AUTH_PUBLIC_KEY.
• 启用身份验证后，缺少颁发者/受众/验证器设置将无法启动。
• 客户端必须发送 Authorization: Bearer <JWT>.

MCP传输配置

传输和网络绑定是配置驱动的（运行时代码中没有硬编码的主机/端口）：

# Local MCP client default
export FINOS_MCP_MCP_TRANSPORT=stdio

# HTTP exposure example
export FINOS_MCP_MCP_TRANSPORT=http
export FINOS_MCP_MCP_HOST=127.0.0.1
export FINOS_MCP_MCP_PORT=8000

活体运输测试

# End-to-end stdio MCP test
FINOS_RUN_LIVE_MCP_TEST=1 ./venv/bin/pytest -q tests/integration/test_live_mcp_server.py

# End-to-end HTTP MCP test (starts server + probes /mcp)
./scripts/test-http-transport.sh

# End-to-end HTTP auth boundary test (unauthorized/forbidden/authorized)
./scripts/test-auth-http-transport.sh

高级配置参考

使用 .env.example 作为规范源，并在生产环境中被环境覆盖。

生产基线：

• FINOS_MCP_MCP_AUTH_ENABLED=true
• FINOS_MCP_MCP_TRANSPORT=http （或 streamable-http)TLS入口后面
• FINOS_MCP_MCP_HOST=127.0.0.1 当由反向代理代理代理时
• 配置 FINOS_MCP_MCP_AUTH_JWKS_URI, FINOS_MCP_MCP_AUTH_ISSUER, FINOS_MCP_MCP_AUTH_AUDIENCE

上线审批门

运行全自动释放门：

./scripts/go-live-gate.sh

包括：

• 跟踪文件夹卫生检查
• 清洁作业树执法
• 绒毛和类型检查
• 回归测试
• 实时stdio/HTTP/auth传输检查
• 依赖性漏洞扫描

内容源

内容覆盖

• 框架数据：直接查阅治理框架文件
• 动态加载：从官方来源自动获取内容
• FINOS内容：人工智能治理风险和缓解措施 FINOS人工智能治理框架，根据CC BY 4.0许可证使用

性能特征

• 响应时间：通过智能缓存实现快速缓存响应时间
• 可靠性：断路器保护和错误边界管理
• 可扩展性：具有可配置缓存限制的内存高效设计
• 安全：全面的DoS保护和请求验证

文档

入门指南

• 安装指南 -连接到编辑器（5分钟）
• 用户指南 -所有工具的全面使用指南

API与集成

• API文档 -所有11个MCP工具的完整API参考资料
• 框架架构 -系统设计和模式
• MCP一致性矩阵 -已实施/部分/超出范围的能力图

支持和故障排除

• 故障排除 -常见问题和解决方案
• 工具参考 -所有11个MCP工具的完整指南
• 架构决策记录 -关键架构原理和政策决策
• GitHub 仓库 -源代码和问题

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改并添加测试
4. 运行CI等效检查： ./scripts/ci-local.sh
5. 使用MCP CLI进行测试： mcp list tools
6. 提交拉取请求

需要帮助

• 报告问题
• 提出问题
• 全部文件

许可证

• 软件：Apache 2.0许可证
• FINOS内容：CC BY 4.0许可证