MCP Server

MCP 服务

一个 Model Context Protocol (MCP) 服务的 Python 实现，提供各种工具，让 AI 助手能够在安全、受控的环境中执行操作。

请注意，此 README 主要由 AI 编写。

安装

1. 确保已安装 Python 3.14+
2. 克隆此仓库
3. 安装依赖项：

pip install -e .

或者使用现代 Python 包管理器，例如 uv：

uv pip install -e .

配置

MCP 服务需要在 ~/.mcp-server/config.yml 中提供配置文件，文件结构如下：

# Operating system
os: Linux

# Brave Search API configuration
braveSearch:
  apiUrl: "https://api.search.brave.com/res/v1/web/search"
  apiKey: "your-brave-api-key"

# Database connection settings
database:
  min_size: 1
  max_size: 3
  max_queries: 5000  # optional: connections are recycled after this many queries
  max_inactive_connection_lifetime: 300  # optional: seconds
  
  # Database connection profiles
  musiciandb:  # This is referenced by --db-name parameter
    vendor: postgresql
    dbname: "postgresdb"
    host: "localhost"
    port: 5432
    readonly:
      # credentials for readonly access
      username: "readonly"
      password: "readonly"
    full:
      # credentials for full access
      username: "admin"
      password: "secret"

# Browser command for opening URLs
browserCommand: firefox

Gradle 设置

若要在 Gradle 项目中使用 get_source工具，需要将此任务添加到 build.gradle 中

tasks.register('listClassesInDeps')  {
    doLast {
        configurations.compileClasspath.resolve().each { file ->
            if (file.name.endsWith('.jar')) {
                println file.absolutePath
            }
        }
        configurations.runtimeClasspath.resolve().each { file ->
            if (file.name.endsWith('.jar')) {
                println file.absolutePath
            }
        }
    }
}

使用方法

运行 MCP 服务：

python mcp_server_low.py [--project-folder /path/to/workspace] [--db-name musiciandb] [--build-tool Maven|Gradle]

参数：

• --project-folder：可选。当前工作区或项目目录的路径
• --db-name：可选。要从配置文件中使用的数据库配置名称
• --build-tool：可选。指定 'Maven' 或 'Gradle' 以支持 Java 项目

VS Code 中集成 GitHub Copilot

若要将此 MCP 服务与 VS Code 集成，以便配合 GitHub Copilot 使用，请按以下步骤操作：

前提条件

1. 确保已安装最新版 VS Code
2. 确保 GitHub Copilot 已安装，并已在 VS Code 中正确配置
3. MCP 服务必须在本地计算机上运行

配置步骤

打开 VS Code 设置（文件 > 首选项 > 设置，或在 macOS 上按 Cmd+,），并将以下配置添加到 settings.json：

"github.copilot.advanced": {
  "mcp": {
    "servers": [
      {
        "name": "Python MCP Server",
        "transport": "stdio",
        "command": "uv",
        "args": [
          "/path/to/your/mcp-server/mcp_server_low.py",
          "--project-folder",
          "${workspaceFolder}",
          "--db-name",
          "musiciandb",
          "--build-tool",
          "Maven"
        ],
        "description": "Local Python MCP Server providing database, web, and system tools"
      }
    ]
  }
}

2. 将 /path/to/your/mcp-server/mcp_server.py 替换为 MCP 服务脚本的实际路径，并将 your-db-name 替换为数据库配置名称。

3. 保存设置并重启 VS Code。

在 Copilot 中使用 MCP 工具

完成配置后，GitHub Copilot 即可访问并使用 MCP 服务提供的工具：

1. 在 VS Code 中打开 Copilot Chat（按 Ctrl+Shift+I 或点击 Copilot Chat 图标）

2. 让 Copilot 使用 MCP 服务提供的工具执行操作：

   Can you get the current time from the system?
   

   Please search for information about Python best practices.
   

3. Copilot 将自动使用相应的 MCP 工具来完成你的请求。

故障排除

如果 MCP 服务集成遇到问题：

1. 检查 MCP 服务是否正常运行
2. 确认 VS Code 设置是否正确
3. 在 VS Code 开发人员工具中查找错误消息（帮助 > 切换开发人员工具）
4. 检查 mcp_server.log 文件中是否有服务端错误

团队使用说明

若要与团队共享 MCP 服务配置：

1. 将 MCP 服务配置添加到工作区设置，而不是用户设置
2. 将配置存储在仓库中的 .vscode/settings.json 文件内
3. 确保所有团队成员都已安装并正确配置 MCP 服务

可用工具

MCP 服务为 AI 助手提供以下工具：

数据库操作

• readonly_sql_query(dbname, query)：在 PostgreSQL 或 SqlServer 数据库上执行只读 SQL 查询，并以 JSON 格式返回结果
• modifying_sql_statement(dbname, statement)：在 PostgreSQL 或 SqlServer 数据库上执行 SQL 语句以修改数据（仅在配置了“full”数据库凭据时可用）

网页交互

• web_search(query)：使用 Brave Search API 搜索网页信息。返回 URL、描述以及从热门结果中获取的内容（HTML 内容会转换为文本）
• open_in_browser(url)：在本地浏览器中打开 URL 或 HTML 文件
• http_get_request(url, headers)：向指定 URL 发起 HTTP GET 请求，可选提供请求头

Java 构建工具（仅在配置了 buildTool 时可用）

• get_source(class_name)：返回 Java 类的源代码（不适用于 Java 标准库类）
• get_javadoc(class_name)：获取 Java 类的 Javadoc（不适用于 Java 标准库类）

API

MCP 服务

该服务使用 MCP Python 软件包中的低级 MCP 实现，并配置为通过 stdio 传输进行安全通信。 需要使用低级实现有 2 个原因：

• 工具列表中的条目取决于启动参数
• 如果 MCP 客户端提供了 roots/list，则会使用它来确定项目工作区路径（Copilot 会提供）

MCP 服务方法

• @server.list_tools()：用于注册返回可用 MCP 工具的函数的装饰器
• @server.call_tool()：用于注册处理所有工具调用的函数的装饰器
• server.run()：使用 stdio 传输和初始化选项启动 MCP 服务
• server_lifespan()：用于管理服务启动和关闭生命周期（包括资源清理）的异步上下文管理器

客户端用法

客户端可以使用任何 MCP 客户端实现连接到此 MCP 服务。客户端示例请参阅 Model Context Protocol 仓库。

开发

先决条件

• Python 3.12+
• PostgreSQL（用于数据库工具）
• Brave Search API 密钥（用于网页搜索功能）

项目结构

• mcp_server_low.py：包含工具定义的主服务实现
• pyproject.toml：项目和软件包管理配置（使用 uv）
• bin/：包含辅助脚本和可执行文件
  • gradle-decompile.sh：用于反编译 Gradle 项目的脚本
  • jd-cli.jar：Java 反编译器命令行工具
• tests/：包含单元测试和集成测试
  • test_mcp_low.py：低级 MCP 服务测试
  • test_page.html：测试 HTML 页面
• utils/：实用模块
  • args.py：命令行参数解析
  • db.py：数据库连接和上下文管理
  • helpers.py：通用实用函数
  • mcp.py：MCP 相关实用工具
  • web.py：HTTP 客户端实用工具和 HTML 处理

许可证

MIT