使用说明

项目简介

本项目 'github-analysis' 提供了一个基于 Model Context Protocol (MCP) 的服务器，用于分析 GitHub 仓库。它包含两个核心组件：

MCP 服务器: 提供工具以标准化的 MCP 接口获取 GitHub 数据，目前支持获取仓库信息和提交历史。
MCP 客户端: 连接到 MCP 服务器，利用获取的数据和 Ollama 等 LLM 进行仓库分析，并提供命令行交互界面。

通过 MCP 架构，客户端和服务端分离，使得数据获取和分析解耦，方便扩展和维护。

主要功能点

仓库信息分析: 获取并分析 GitHub 仓库的元数据，例如仓库大小、语言、 stars 数量等。
提交历史分析: 获取并分析仓库的提交历史，例如最近的提交、提交频率、代码变更模式等。
AI 驱动的洞察: 利用 Ollama 等 LLM 对仓库数据进行分析，提供智能化的洞察和总结。
自定义分析: 允许用户自定义分析 Prompt，针对仓库提出更具体的问题。

安装步骤

克隆仓库

git clone https://github.com/frangkli/github-analysis.git
cd github-analysis

创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
.venv\Scripts\activate      # Windows

安装项目依赖
```
pip install -e .
```
安装 Ollama 并下载模型
- 访问 Ollama 官网安装 Ollama。
- 确保已下载 'qwen2.5:7b' 模型，运行命令 'ollama pull qwen2.5:7b' 进行下载。

配置 GitHub Token (可选)

为了提高 GitHub API 的速率限制，建议设置 GitHub Personal Access Token。

获取 Token 后，将其设置为环境变量 'GITHUB_TOKEN':

export GITHUB_TOKEN=your_github_token_here  # Linux/macOS
set GITHUB_TOKEN=your_github_token_here     # Windows

服务器配置

MCP 客户端需要配置以下 JSON 格式的服务器信息才能连接到本 MCP 服务器。以下是基于本项目仓库信息生成的配置，客户端需要能够读取并使用这些配置来启动和连接服务器。

{
  "server_name": "GitHub Analysis",
  "transport": "stdio",
  "stdio_command": "python",
  "stdio_args": [
    "github_analysis/server/server.py"
  ],
  "stdio_env": {
    "PYTHONUNBUFFERED": "1",
    "PYTHONPATH": ".."
  }
}

配置参数说明:

'server_name': 服务器名称，用于标识服务器功能，这里是 "GitHub Analysis"。
'transport': 传输协议，本项目 MCP 服务器使用 'stdio' 标准输入输出进行通信。
'stdio_command': 启动服务器的命令，这里是 'python'，假设 Python 环境已配置到系统 PATH 中。
'stdio_args': 启动服务器命令的参数列表，这里指向 'github_analysis/server/server.py' 脚本文件，该脚本文件是 MCP 服务器的入口点。
'stdio_env': 启动服务器进程时需要设置的环境变量。
- 'PYTHONUNBUFFERED: "1"': 强制 Python 输出不缓冲，保证 MCP 通信的实时性。
- 'PYTHONPATH: ".."': 将项目根目录添加到 Python 模块搜索路径，以便服务器程序能找到 'github_analysis' 包。这里假设客户端启动命令的当前工作目录位于 'github_analysis/client' 目录下， '..' 代表父目录，即项目根目录。 请注意，如果客户端启动目录不同，'PYTHONPATH' 的设置可能需要相应调整。

重要提示: MCP 客户端需要根据上述配置信息，构建 'StdioServerParameters' 对象，并使用 'stdio_client' 方法与 MCP 服务器建立连接。客户端代码示例中已经展示了如何使用这些配置信息连接服务器，用户通常无需手动配置 JSON 文件，而是由客户端程序内部处理配置。

基本使用方法

启动 MCP 服务器 在终端中，进入项目根目录 'github-analysis'，运行以下命令启动 MCP 服务器：
```
github-analysis server
```
服务器成功启动后，会显示 '✨ Starting GitHub Analysis Server...' 的提示信息。
启动 MCP 客户端 在另一个新的终端中，同样进入项目根目录 'github-analysis'，运行以下命令启动 MCP 客户端，并指定要分析的 GitHub 仓库的 owner 和 repo 名称：
```
github-analysis client <owner> <repo>
```
例如，分析 'frangkli/github-analysis' 仓库，可以运行：
```
github-analysis client frangkli github-analysis
```
客户端交互 客户端启动后，会连接到服务器，并显示可用的工具列表。之后，会进入交互式菜单，您可以选择不同的分析选项：
- '🔄 Analyze recent commits': 分析最近的提交历史。
- '📊 Analyze repository information': 分析仓库的基本信息。
- '🔍 Custom analysis prompt': 自定义分析 Prompt，进行更细致的分析。
- '👋 Exit': 退出客户端。
根据菜单提示选择相应的选项，客户端会调用服务器工具获取数据，并使用 Ollama 进行分析，最终将分析结果展示在终端中。
Ollama-only 模式 (可选) 如果不想使用 MCP 服务器，只想直接使用 Ollama 进行分析，可以在启动客户端时添加 '--disable-tools' 参数：
```
github-analysis client <owner> <repo> --disable-tools
```
在这种模式下，客户端不会连接 MCP 服务器，所有的数据分析都基于 Ollama 的通用知识，无法获取实时的仓库信息和提交历史。

关键词