模型上下文协议服务器

MPO MCP Server是一个基于FastMCP构建的模型上下文协议服务器,提供与GitHub仓库、Confluence文档和Databricks Unity Catalog的强大集成,支持AI助手和LLM与开发及数据生态系统的无缝交互。

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

使用说明

MPO MCP 服务器

一个基于(某种技术或框架,原文未指明)构建的全面模型上下文协议(MCP)服务器 FastMCP 该工具与GitHub仓库、Confluence文档和Databricks Unity目录提供了强大的集成功能。

🚀 表情符号“🚀”在中文中通常被翻译为“火箭”或直接用该符号表示火箭的形象,不直接对应具体的中文词汇,但在描述时可意译为“火箭”。所以,这个表情可以理解为“🚀 火箭”。 使用FastMCP构建! 这台服务器利用了 FastMCP这是一个现代的、基于装饰器的框架,用于构建MCP服务器,且代码样板极少。

📚 目录

概述

MPO MCP服务器使AI助手和大型语言模型(LLM)能够与您的开发和数据生态系统无缝交互。它通过模型上下文协议提供了一套全面的工具,使智能代理能够:

  • GitHub浏览仓库、搜索代码、阅读文件、管理分支和拉取请求
  • “Confluence”翻译成中文是“汇流”或“交汇”。这个词通常用来描述两个或多个事物、思想、水流等的汇聚或融合搜索并检索文档,列出空间和页面
  • Databricks查询Unity Catalog元数据,执行SQL查询,探索数据架构

该服务器采用模块化架构设计,允许您仅配置所需的服务。

特点/功能

🔧 灵活配置

  • 模块化设计仅启用您所需的服务(GitHub、Confluence、Databricks 或任意组合)
  • 基于环境的简单 .env 带验证的文件配置
  • 安全通过环境变量管理的API令牌和凭据

🚀 多种使用模式

  1. 交互式大型语言模型助手具有自主工具选择功能的自然语言接口
  2. MCP 服务器与Claude Desktop及其他MCP客户端的直接集成
  3. 命令行界面通过命令行界面(CLI)直接调用工具

📊 综合工具集

  • 18个GitHub工具完整的仓库管理和代码探索功能
  • 5个Confluence工具全面的文档搜索与检索
  • 10个Databricks工具完整的Unity Catalog元数据和SQL执行

安装

先决条件

  • Python 3.10或更高版本
  • pip 或者 紫外线 用于包管理
  • 您想要使用的服务的API凭据

快速设置

  1. 克隆仓库:
cd /Users/bsang2/Desktop/mcp_demo/mpo-mcp
  1. 安装依赖项:
pip install -r requirements.txt

或者使用紫外线(更快):

uv pip install -r requirements.txt
  1. 创建配置文件:
cp .env.example .env  # If example exists
# Or create .env manually
  1. 添加您的凭据 to .env (见 配置)

软件包安装

你也可以将其安装为一个包:

pip install -e .

这启用了命令行工具:

  • mpo-mcp-server运行MCP服务器
  • mpo命令行界面

配置

环境变量

创建一个 .env 在项目根目录中创建文件并填入您的凭据:

# ============================================
# Anthropic Configuration (for LLM Assistant)
# ============================================
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# ============================================
# GitHub Configuration
# ============================================
GITHUB_TOKEN=your_github_token_here
GITHUB_ORG=your_default_org_or_username

# ============================================
# Confluence Configuration
# ============================================
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=your_email@example.com
CONFLUENCE_API_TOKEN=your_confluence_api_token
CONFLUENCE_SPACE_KEY=your_default_space_key

# ============================================
# Databricks Configuration
# ============================================
DATABRICKS_HOST=https://your-workspace.databricks.com
DATABRICKS_TOKEN=your_databricks_token
DATABRICKS_CATALOG=your_default_catalog
DATABRICKS_WAREHOUSE_ID=your_sql_warehouse_id

获取API凭证

Anthropic API密钥(用于交互式大型语言模型助手)

  1. 参观 console.anthropic.com 翻译为中文是:“Anthropic 控制台”。不过,通常“console”在中文里并不直接翻译,而是根据上下文或品牌名称来翻译整个网址或域名。在这里,“Anthropic”是一个公司名,通常保留原样,而“console”在这里可以理解为该公司的某个控制台或管理界面。所以,整个网址“console.anthropic.com”可以理解为“Anthropic 的控制台(或管理界面)网址”。但为了简洁,我们通常只翻译“Anthropic”部分,即“Anthropic 控制台”,并保留“.com”作为网址后缀的指示
  2. 注册或登录
  3. 导航至API密钥
  4. 创建一个新的API密钥
  5. 复制到 .env 文件

GitHub 个人访问令牌

  1. 前往 GitHub 设置 → 开发者设置 → 个人访问令牌 → 令牌(经典)
  2. 生成带有作用域的新令牌:
    • repo (针对私有仓库)
    • read:org (用于组织数据)
    • user (针对用户数据)
  3. 将令牌复制到 .env 文件

Confluence API令牌

  1. 访问 id.atlassian.com/管理个人资料/安全/API令牌
  2. 创建API令牌
  3. 使用您的Atlassian账户电子邮件作为用户名
  4. 复制令牌到 .env 文件

Databricks访问令牌

  1. 前往您的Databricks工作区
  2. 点击用户设置 → 开发者
  3. 管理访问令牌 → 生成新令牌
  4. 设置过期时间和备注
  5. 复制令牌到 .env 文件

服务验证

服务器在启动时自动验证配置:

  • 工具仅对已正确配置的服务开放
  • 支持部分配置(例如,仅支持GitHub)
  • 明确显示缺少凭据的错误信息

使用方法

方法1:交互式大型语言模型助手(推荐)🤖

使用服务器的最简单方式——一个能够自主选择和使用工具的对话式界面:

python llm_assistant.py

特点:

  • 自然语言查询
  • 自主工具选择
  • 情境感知响应
  • 对话历史
  • 后续问题

示例会话:

💬 You: What are the most popular repositories from nike-goal-analytics-mpo?
🤖 Assistant: [Analyzes and calls github_list_repositories]
            Here are Facebook's top repositories:
            1. React - 210K stars...

💬 You: Show me the README from the React repository
🤖 Assistant: [Calls github_get_file_contents]
            Here's the React README...

💬 You: Search for "useState" in that repo
🤖 Assistant: [Calls github_search_code]
            Found 147 results for "useState"...

要求: 设置 ANTHROPIC_API_KEY 在 .env

看 docs/GETTING_STARTED_LLM_ASSISTANT.md 翻译为中文是:docs/入门指南_大型语言模型助手.md 以获取详细文档。

方法2:MCP服务器(适用于Claude桌面及其他客户端)

运行服务器以通过模型上下文协议暴露工具:

python -m mpo_mcp.server

或者如果作为包安装:

mpo-mcp-server

与Claude桌面版的集成

在您的Claude桌面配置中添加:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows(视窗操作系统) %APPDATA%\Claude\claude_desktop_config.json

选项1:使用.env文件(推荐)

{
  "mcpServers": {
    "mpo-mcp": {
      "command": "python",
      "args": ["-m", "mpo_mcp.server"],
      "cwd": "/Users/bsang2/Desktop/mcp_demo/mpo-mcp"
    }
  }
}

选项2:显式环境变量

{
  "mcpServers": {
    "mpo-mcp": {
      "command": "python",
      "args": ["-m", "mpo_mcp.server"],
      "cwd": "/Users/bsang2/Desktop/mcp_demo/mpo-mcp",
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GITHUB_ORG": "your_org",
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_USERNAME": "your_email@example.com",
        "CONFLUENCE_API_TOKEN": "your_token",
        "CONFLUENCE_SPACE_KEY": "your_space",
        "DATABRICKS_HOST": "https://your-workspace.databricks.com",
        "DATABRICKS_TOKEN": "your_token",
        "DATABRICKS_CATALOG": "your_catalog",
        "DATABRICKS_WAREHOUSE_ID": "your_warehouse_id"
      }
    }
  }
}

见 docs/CURSOR_MCP_SETUP.md 翻译为中文是:docs/光标MCP设置.md 用于Cursor AI集成。

方法3:命令行界面

通过CLI直接调用工具:

# GitHub commands
mpo github repos --org nike-goal-analytics-mpo --limit 5
mpo github repo --name nike-goal-analytics-mpo/msc-dft-monorepo
mpo github search --query "useState" --repo nike-goal-analytics-mpo/msc-dft-monorepo
mpo github file --repo nike-goal-analytics-mpo/msc-dft-monorepo --path README.md
mpo github branches --repo nike-goal-analytics-mpo/msc-dft-monorepo
mpo github prs --repo nike-goal-analytics-mpo/msc-dft-monorepo --state open

# Confluence commands
mpo confluence spaces --limit 10
mpo confluence pages --space DOCS --limit 20
mpo confluence page --id 123456789
mpo confluence search --query "architecture" --space TECH
mpo confluence page-by-title --title "Getting Started"

# Databricks commands
mpo databricks catalogs
mpo databricks schemas --catalog main
mpo databricks tables --catalog main --schema default
mpo databricks schema --catalog main --schema default --table users
mpo databricks search --query customer --catalog main
mpo databricks catalog --name main
mpo databricks query --sql "SELECT * FROM main.default.users LIMIT 10"
mpo databricks warehouses

# Help
mpo --help
mpo github --help
mpo confluence --help
mpo databricks --help

看 docs/CLI_GUIDE.md 翻译为中文是:docs/命令行接口指南.md 并且 docs/CLI_EXAMPLES.md 翻译为中文是:文档/命令行接口示例.md 用于全面的命令行界面(CLI)文档。

可用工具

GitHub 工具(6款工具)

1. github_list_repositories

列出用户或组织的仓库列表。

参数:

  • org (可选):组织或用户名(默认为 GITHUB_ORG)
  • limit (默认:30):最大仓库数量

返回值: 包含名称、描述、星标数、分支数、语言等信息的仓库列表。

示例:

{
  "org": "nike-goal-analytics-mpo",
  "limit": 10
}

2. github_get_repository_info

获取特定仓库的详细信息。

参数:

  • repo_name (必填):完整仓库名称(例如,“nike-goal-analytics-mpo/msc-dft-monorepo”)

返回: 包含星标、分支、主题、许可证等详细仓库元数据。

示例:

{
  "repo_name": "nike-goal-analytics-mpo/msc-dft-monorepo"
}

3. github_search_code

在GitHub仓库中搜索代码。

参数:

  • query (必填):搜索查询
  • repo (可选):将搜索限制在特定仓库内
  • limit (默认:10):最大结果数

返回值: 代码匹配项列表,包含文件路径和URL

示例:

{
  "query": "useState",
  "repo": "nike-goal-analytics-mpo/msc-dft-monorepo",
  "limit": 5
}

4. github_get_file_contents

从存储库中读取文件内容。

参数:

  • repo_name (必填):完整的仓库名称
  • file_path (必填):文件路径
  • ref (可选):分支、标签或提交SHA

返回值: 文件内容和元数据

示例:

{
  "repo_name": "nike-goal-analytics-mpo/msc-dft-monorepo",
  "file_path": "README.md"
}

5. github_list_branches

列出仓库中的分支。

参数:

  • repo_name (必填):完整仓库名称
  • limit (默认:20):最大分支数

返回值: 具有保护状态和提交SHA的分支列表

示例:

{
  "repo_name": "nike-goal-analytics-mpo/msc-dft-monorepo",
  "limit": 10
}

6. github_get_pull_requests

检索某个仓库的拉取请求。

参数:

  • repo_name (必填):完整仓库名称
  • state (默认:“open”):PR 状态(“open”、“closed”或“all”)
  • limit (默认:20):最大请求数(PRs)

返回值: 包含状态、作者、日期等信息的拉取请求列表。

示例:

{
  "repo_name": "nike-goal-analytics-mpo/msc-dft-monorepo",
  "state": "open",
  "limit": 10
}

Confluence 工具(5种工具)

1. confluence_list_pages

列出Confluence空间中的页面。

参数:

  • space_key (可选):空格键(默认为 CONFLUENCE_SPACE_KEY)
  • limit (默认:25):最大页数

返回值: 包含标题、ID和URL的页面列表

示例:

{
  "space_key": "DOCS",
  "limit": 20
}

2. confluence_get_page_content

获取Confluence页面的全部内容。

参数:

  • page_id (必填):页面ID

返回值: 包含元数据、版本信息以及HTML/存储内容的页面内容

示例:

{
  "page_id": "123456789"
}

3. confluence_search_pages

在Confluence中搜索页面。

参数:

  • query (必填):搜索查询
  • space_key (可选):限制在特定空间内
  • limit (默认:20):最大结果数

返回值: 搜索结果,含摘要及相关性

示例:

{
  "query": "API documentation",
  "space_key": "TECH",
  "limit": 10
}

4. confluence_get_page_by_title

通过精确标题查找页面。

参数:

  • title (必填):页面标题
  • space_key (可选):空格键(默认为 CONFLUENCE_SPACE_KEY)

返回值: 页面内容和元数据

示例:

{
  "title": "Getting Started Guide",
  "space_key": "DOCS"
}

5. confluence_list_spaces

列出可用的 Confluence 空间。

参数:

  • limit (默认:25):最大空间数

返回值: 包含密钥、名称和URL的空间列表

示例:

{
  "limit": 10
}

Databricks 工具(10种工具)

1. databricks_list_catalogs

列出所有Unity Catalog目录。

参数: 无

返回值: 包含名称、所有者和存储根目录的目录列表

示例:

{}

2. databricks_list_schemas

在目录中列出模式。

参数:

  • catalog_name (可选):目录名称(默认为 DATABRICKS_CATALOG)

返回值: 包含全名和元数据的模式列表

示例:

{
  "catalog_name": "main"
}

3. databricks_list_tables

列出模式中的表。

参数:

  • schema_name (必填):模式名称
  • catalog_name (可选):目录名称(默认为 DATABRICKS_CATALOG)

返回值: 包含名称、类型、格式和位置的表格列表

示例:

{
  "catalog_name": "main",
  "schema_name": "default"
}

4. databricks_get_table_schema

获取表的详细模式。

参数:

  • table_name (必填):表名
  • schema_name (必填):模式名称
  • catalog_name (可选):目录名称(默认为 DATABRICKS_CATALOG)

返回值: 完整的表模式,包括列、类型和属性

示例:

{
  "table_name": "users",
  "catalog_name": "main",
  "schema_name": "default"
}

5. databricks_search_tables

按名称模式搜索表。

参数:

  • query (必填):搜索查询(表名模式)
  • catalog_name (可选):限制为特定目录
  • max_results (默认:50):最大结果数

返回值: 匹配表列表

示例:

{
  "query": "customer",
  "catalog_name": "main",
  "max_results": 20
}

6. databricks_get_catalog_info

获取详细的目录信息。

参数:

  • catalog_name (必填):目录名称

返回值: 目录元数据,包括属性和配置

示例:

{
  "catalog_name": "main"
}

7. databricks_get_schema_info

获取详细的模式信息。

参数:

  • catalog_name (必填):目录名称
  • schema_name (必填):模式名称

返回: 模式元数据和属性

示例:

{
  "catalog_name": "main",
  "schema_name": "default"
}

8. databricks_execute_query

在Databricks上执行SQL查询。

参数:

  • query (必填):要执行的SQL查询
  • catalog_name (可选):目录上下文(默认为 DATABRICKS_CATALOG)
  • warehouse_id (可选):SQL 仓库 ID(默认为 DATABRICKS_WAREHOUSE_ID)

返回值: 带有列和数据行的查询结果

示例:

{
  "query": "SELECT * FROM main.default.users LIMIT 10",
  "catalog_name": "main",
  "warehouse_id": "abc123def456"
}

9. databricks_list_warehouses

列出可用的SQL仓库。

参数: 无

返回值: 带有ID、名称、状态和配置的SQL仓库列表

示例:

{}

10. databricks_list_sql_warehouses

别名为 databricks_list_warehouses.

文档

全面的文档资料可在 docs/ 目录:

入门指南

工具与命令行界面(CLI)

FastMCP

建筑与理念

发展

项目结构

mpo-mcp/
├── mpo_mcp/                    # Main package
│   ├── __init__.py            # Package initialization
│   ├── server.py              # FastMCP server implementation
│   ├── config.py              # Configuration management
│   ├── github_tools.py        # GitHub integration (6 tools)
│   ├── confluence_tools.py    # Confluence integration (5 tools)
│   ├── databricks_tools.py    # Databricks integration (10 tools)
│   └── cli.py                 # Command-line interface
├── docs/                       # Comprehensive documentation
├── llm_assistant.py           # Interactive LLM assistant
├── example_usage.py           # Usage examples
├── quick_query.py             # Quick query utility
├── requirements.txt           # Python dependencies
├── pyproject.toml             # Package configuration
├── .env                       # Environment variables (not in git)
├── .gitignore                 # Git ignore rules
└── README.md                  # This file

添加新工具

  1. 实施该工具 在相应的工具文件中:
# In mpo_mcp/github_tools.py
async def new_github_feature(self, param: str) -> Dict[str, Any]:
    """
    Description of the new feature.
    
    Args:
        param: Parameter description
        
    Returns:
        Result description
    """
    # Implementation
    pass
  1. 注册该工具 在 server.py:
@mcp.tool()
async def github_new_feature(param: str) -> dict:
    """Tool description for MCP clients.
    
    Args:
        param: Parameter description
    """
    return await github_tools.new_github_feature(param=param)
  1. 添加CLI命令 在 cli.py (可选):
@github_group.command()
@click.option('--param', required=True, help='Parameter description')
def new_feature(param: str):
    """Command description."""
    result = asyncio.run(github_tools.new_github_feature(param=param))
    click.echo(json.dumps(result, indent=2))

测试工具

你可以通过编程方式测试单个工具:

import asyncio
from mpo_mcp.github_tools import GitHubTools

async def test():
    tools = GitHubTools()
    repos = await tools.list_repositories(org="nike-goal-analytics-mpo", limit=5)
    print(repos)

asyncio.run(test())

代码质量

  • 类型提示所有函数都使用类型提示
  • **文档字符串(或称为docstrings)**所有公共方法的完整文档字符串
  • 错误处理优雅地处理错误,并提供信息丰富的消息
  • 记录日志全程采用结构化日志记录

依赖项

核心依赖项:

  • fastmcp>=0.1.0 - MCP服务器框架
  • PyGithub>=2.1.1 GitHub API 客户端
  • atlassian-python-api>=3.41.0 - Confluence API 客户端
  • databricks-sdk>=0.18.0 Databricks API客户端
  • python-dotenv>=1.0.0 - 环境变量管理
  • anthropic>=0.39.0 - 用于大型语言模型助手的Anthropic API

见 requirements.txt(需求文件) 以获取完整列表。

故障排除

服务器无法启动

问题: 服务器无法启动或显示导入错误

解决方案:

  1. 验证Python版本: python --version (必须为3.10及以上版本)
  2. 重新安装依赖项: pip install -r requirements.txt --force-reinstall
  3. 检查是否存在冲突的软件包: pip list | grep mcp
  4. 验证虚拟环境: which python

工具未显示

问题: 预期的工具未在MCP客户端中显示

解决方案:

  1. 检查服务器日志中的配置验证
  2. 验证凭据在 .env 文件
  3. 确保 .env 位于正确位置(项目根目录)
  4. 检查环境变量是否已加载: python -c "from mpo_mcp.config import Config; print(Config.validate_github())"
  5. 配置更改后重启MCP客户端

API认证错误

GitHub:

  • 验证令牌具有正确的范围(repo, read:org)
  • 检查令牌是否未过期
  • 测试代币: curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

汇合点;交汇处

  • 验证URL格式(必须包含https://)
  • 检查API令牌是否有效(非密码)
  • 确保用户名为电子邮件地址
  • 测试: curl -u email@example.com:API_TOKEN https://your-domain.atlassian.net/wiki/rest/api/space

Databricks(公司名,可译为“达布莱克斯”或根据官方中文名翻译,此处保留原英文以体现专有名词特性):

  • 验证工作区URL是否正确
  • 检查令牌是否未过期
  • 确保令牌具有适当的权限
  • 测试: curl -H "Authorization: Bearer YOUR_TOKEN" https://your-workspace.databricks.com/api/2.0/unity-catalog/catalogs

速率限制

GitHub:

  • 认证请求:每小时5,000次请求
  • 搜索API:每分钟30次请求
  • 使用 limit 参数以减少API调用

汇合点;交汇

  • 云服务:速率限制因计划而异
  • 为生产环境实现指数退避策略

Databricks:(保持原样,作为专有名词,不直接翻译,若需解释性翻译可为“Databricks(公司名,专注于大数据处理与分析)”)

  • 检查工作区配额
  • 使用连接池进行多个查询

Claude桌面集成问题

问题: 在Claude桌面版中未显示的工具

解决方案:

  1. 验证配置文件位置:
    • macOS:(可翻译为)苹果操作系统;(或直接保留原样,因为“macOS”在中文中通常不翻译,直接使用其英文原名) ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. 检查JSON语法是否有效
  3. 验证 cwd 路径是绝对且正确的
  4. 配置更改后重启 Claude 桌面版
  5. 检查Claude Desktop的日志以查找错误

大型语言模型(LLM)助手的问题

问题: 助手无响应或出现错误

解决方案:

  1. 验证 ANTHROPIC_API_KEY 设置正确
  2. 检查API密钥是否有足够的信用额度
  3. 确保FastMCP服务器能够独立启动
  4. 查看控制台输出中的错误信息

连接问题

问题: 工具超时或无法连接

解决方案:

  1. 检查网络连接
  2. 验证防火墙规则是否允许出站HTTPS连接
  3. 使用curl直接测试API端点
  4. 如果在企业防火墙后面,请检查代理设置
  5. 如果连接速度较慢,请增加超时值

调试技巧

  1. 启用详细日志记录:
import logging
logging.basicConfig(level=logging.DEBUG)
  1. 测试配置:
python -c "from mpo_mcp.config import Config; print(f'GitHub: {Config.validate_github()}, Confluence: {Config.validate_confluence()}, Databricks: {Config.validate_databricks()}')"
  1. 运行带日志记录的服务器:
python -m mpo_mcp.server 2>&1 | tee server.log
  1. 测试单个工具:
mpo github repos --org nike-goal-analytics-mpo --limit 1
mpo confluence spaces --limit 1
mpo databricks catalogs

寻求帮助

如果您遇到此处未涵盖的问题:

  1. 查阅相关文件 docs/
  2. 检查服务器日志以获取详细的错误信息
  3. 验证所有凭据是否配置正确
  4. 独立测试API终端点
  5. 检查您是否具有每个服务的适当权限

许可证

此项目仅提供作演示和集成之用,不做其他用途。

做出贡献

欢迎投稿!请确保:

  • 代码遵循现有的风格和规范
  • 所有函数都带有类型提示和文档字符串
  • 新工具已正确注册
  • 文档已相应更新

致谢

构建于:


版本: 0.1.0
python 3.10+
许可证: 麻省理工学院(MIT)
状态: 已准备好投入生产 ✅