GitHub MCP Practice

MCP GitHub+MCP Client项目

这个项目 GitHub MCP服务器哇 MCP客户端（FastAPI+语言图） 由两部分组成。

🏗️ 项目结构

├── mcp_github/          # GitHub MCP Server (fastMCP 기반)
└── mcp_client/          # MCP Client (FastAPI + LangGraph)

______________________________________________________________________

🚀 MCP GitHub服务器

使用fastMCP构建的GitHub MCP服务器。

设置

# 가상환경 활성화
source venv/bin/activate

# 개발 모드로 설치
pip install -e .

设置环境变量

GitHub API需要Personal Access Token：

1. 在中创建新令牌
2. 所需权限： repo, user
3. 设置环境变量：

# .env 파일 생성 (프로젝트 루트에)
echo "GITHUB_TOKEN=your_token_here" > .env

# 또는 직접 환경변수 설정
export GITHUB_TOKEN=your_token_here

运行

# 가상환경 활성화
source venv/bin/activate

# MCP 서버 실행
python -m mcp_github.server

Cursor设置

要从Cursor连接MCP服务器，请使用以下设置：

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "mcp_github.server"],
      "cwd": "/Users/hyunwoo/Desktop/클테코/20250904_githubMCP",
      "env": {
        "PYTHUB_TOKEN": "your_github_token_here",
        "PYTHONPATH": "/Users/hyunwoo/Desktop/클테코/20250904_githubMCP"
      }
    }
  }
}

可用的工具

只读工具（Read Tools）

健康

检查服务器状态

{
  "status": "ok"
}

getRepo

查看GitHub存储库信息

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice"
}

listPullRequests

查看Pull Request列表

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "state": "open"
}

getPRDiff

Pull Request的diff查询

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "number": 1
}

getFile

查看存储库中的文件内容

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "path": "README.md",
  "ref": "main"
}

写入工具（Write Tools）

createOrUpdateFile

创建或修改文件

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "path": "new_file.txt",
  "content": "Hello, World!",
  "message": "Add new file",
  "branch": "main",
  "committer_name": "Your Name",
  "committer_email": "your.email@example.com"
}

\_删除文件

删除文件

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "path": "file_to_delete.txt",
  "message": "Delete file",
  "branch": "main"
}

createBranch

创建新分支

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "new_branch": "feature-branch",
  "base_branch": "main"
}

createCommitWithMultipleFiles

一次提交多个文件

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "files": [
    {
      "path": "file1.txt",
      "content": "Content 1",
      "operation": "create"
    },
    {
      "path": "file2.txt",
      "content": "Updated content",
      "operation": "update"
    }
  ],
  "message": "Multiple file changes",
  "branch": "main"
}

获取存储库状态

查看存储库状态和最新提交信息

{
  "owner": "J-nowcow",
  "repo": "github-MCP-practice",
  "ref": "main"
}

使用示例

创建和提交文件

1. 创建新文件：

{
  "tool": "createOrUpdateFile",
  "arguments": {
    "owner": "J-nowcow",
    "repo": "github-MCP-practice",
    "path": "docs/new_feature.md",
    "content": "# New Feature\n\nThis is a new feature documentation.",
    "message": "Add new feature documentation"
  }
}

1. 修改文件：

{
  "tool": "createOrUpdateFile",
  "arguments": {
    "owner": "J-nowcow",
    "repo": "github-MCP-practice",
    "path": "README.md",
    "content": "# Updated README\n\nUpdated content here.",
    "message": "Update README"
  }
}

1. 在新分支中工作：

{
  "tool": "createBranch",
  "arguments": {
    "owner": "J-nowcow",
    "repo": "github-MCP-practice",
    "new_branch": "feature/new-ui",
    "base_branch": "main"
  }
}

______________________________________________________________________

🧠 MCP客户端（FastAPI+语言图）

连接Azure OpenAI+GitHub MCP Server MCP客户端（FastAPI+语言图） 项目。

🎯 项目概述

该项目允许用户使用REST API（/chat）发送自然语言请求：

1. MCP服务器（GitHub） 连接→查看可用工具列表
2. LangGraph重构代理 →使用Azure OpenAI模型制定工具执行计划
3. MCP服务器 →运行实际工具并收集结果
4. LangGraph워크플로우 →生成并返回最终响应

🏗️ 体系结构

FastAPI → LangGraph Agent → MCP Server → GitHub
    ↓           ↓              ↓
  /chat → ReAct Workflow → Tools Execution

🚀 快速入门

1.设置虚拟环境

# 가상 환경 생성
python -m venv venv

# 가상 환경 활성화
source venv/bin/activate  # macOS/Linux
# 또는
venv\Scripts\activate     # Windows

2.安装依赖性

pip install -r requirements.txt

3.设置环境变量

.env 在项目根目录中创建文件并添加以下内容：

# MCP Server
MCP_SERVER_URL=http://localhost:3000

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-endpoint.openai.azure.com/
AZURE_OPENAI_API_KEY=your_api_key_here
AZURE_OPENAI_DEPLOYMENT=gpt-4o
AZURE_OPENAI_API_VERSION=2025-01-01-preview
OPENAI_TEMPERATURE=0.1

# HTTP
HTTP_TIMEOUT_SEC=30

4.运行服务器

# 개발 모드로 실행
uvicorn mcp_client.main:app --reload --port 8081

📡 API端点

POST/聊天

处理用户问题并使用MCP工具生成响应。

请求：

{
  "query": "GitHub 이슈 생성해줘",
  "thread_id": "optional_thread_id"
}

回复：

{
  "response": "GitHub 이슈가 생성되었습니다",
  "used_tools": [
    {
      "name": "create_github_issue",
      "arguments": {"title": "...", "body": "..."},
      "result": {"url": "..."}
    }
  ],
  "status": "success",
  "trace": {
    "tool_names": ["create_github_issue"],
    "model_rounds": 2,
    "thread_id": "thread_123"
  }
}

GET/健康

检查服务状态。

回复：

{
  "status": "ok",
  "details": {
    "mcp_client": {"status": "connected", "tool_count": 5},
    "workflow": "ready",
    "tools_available": 5
  }
}

GET/工作流/信息

查看工作流信息。

回复：

{
  "status": "success",
  "workflow_info": {
    "model": "gpt-4o",
    "temperature": 0.1,
    "nodes": ["agent"],
    "checkpointer": "MemorySaver"
  }
}

🛠️ 核心组件

MCPClientManager(mcp_client/mcp_client.py)

• langchain-mcp-adapters的 MultiServerMCPClient 包装类
• 实施异步上下文管理器
• 错误处理和重试逻辑

MCPAgent工作流程mcp_client/agent/workflow.py)

• LangGraph의 StateGraph使用配置ReAct代理
• Azure OpenAI模型与MCP工具集成
• 执行工作流并处理结果

🔧 开发

项目结构

mcp_client/
├── __init__.py
├── main.py                 # FastAPI 엔트리포인트
├── config.py              # 환경변수 설정
├── schemas.py             # Pydantic 모델
├── mcp_client.py          # MCP 서버 연결 관리
└── agent/
    ├── __init__.py
    └── workflow.py        # LangGraph 워크플로우

运行测试

# 전체 테스트
pytest

# 특정 테스트
pytest tests/ -v

# 커버리지
pytest --cov=mcp_client

代码质量

# 린팅
ruff check .

# 포맷팅
ruff format .

# 타입 체크
mypy mcp_client/

📚 技术堆栈

• Python 3.11+
• 快速 API -Web框架
• LangGraph -工作流编排
• langchain mcp适配器 -MCP集成
• 兰开夏 -Azure OpenAI통합
• 派丹蒂克 -数据验证
• 乌维科恩 -ASGI服务器

🔍 故障排除

常见问题

1. MCP服务器连接失败

- 验证MCP服务器是否正在运行 - MCP_SERVER_URL 检查环境变量

1. Azure OpenAI身份验证失败

- 验证API密钥和端点 - 验证部署名称和API版本

1. Import错误

- 验证虚拟环境是否已激活 - pip install -r requirements.txt 运行

检查日志

运行服务器时，可以查看详细日志：

uvicorn mcp_client.main:app --reload --port 8081 --log-level debug

______________________________________________________________________

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

该项目在MIT许可下分发。

📞 支持

如果您遇到问题或有任何问题：

1. 在GitHub Issues上注册问题
2. 检查项目文档
3. 联系开发团队

______________________________________________________________________

开发团队：MCP GitHub+MCP客户端团队\ 上次更新: 2025-09-04\ 版本: 0.1.0