Personal GitHub Assistant MCP

Nisarg Kadam技术处理员

用LangGraph和GPT-4.1-mini构建的生产级个人人工智能助理。接受自然语言查询，并将其智能地路由到网络搜索（DuckDuckGo）和GitHub（通过MCP），然后合成一个连贯的响应。

______________________________________________________________________

架构概述

User Query
    |
    v
[Planner Node]        -- GPT-4.1-mini extracts intent and parameters as JSON
    |
    v
[Router Node]         -- Conditionally routes based on intent
    |
    +---> [Executor Node]   -- Runs tools concurrently via asyncio.gather
    |           |
    v           v
[Synthesizer Node]    -- GPT-4.1-mini generates a natural language response
    |
    v
[Finalizer Node]      -- Standardizes output shape for the API
    |
    v
POST /chat  ->  { response, tools_used, metadata }

LangGraph图形流

该图是一个有向结构，由 StateGraph(AgentState).

条件边：

graph.add_conditional_edges(
    "router",
    route_decision,          # returns "executor" or "synthesizer"
    {"executor": "executor", "synthesizer": "synthesizer"}
)

______________________________________________________________________

工具

网络搜索--DuckDuckGo(app/tools/web_search.py)

• 使用 ddgs Python库（开源，不需要API密钥）
• 在内部运行同步DDGS调用 asyncio.to_thread 保持非阻塞状态
• 最多返回6个结果：标题、代码段、链接、源代码
• 零设置——开箱即用

通过MCP访问GitHub(app/tools/github_tool.py)

• 与官方GitHub MCP服务器通信(@modelcontextprotocol/server-github)超过stdio
• 作为npx子进程自动生成--无需手动启动服务器
• 支持三个操作：

- list_repos --列出配置的GitHub用户名的所有公共存储库 - get_repo_details(repo_name) --获取特定仓库的README和元数据 - summarize_repo(repo_name) --从README推断技术栈并返回结构化摘要

• 需要Node.js 18+和GitHub个人访问令牌 repo + read:user 范围

MCP客户端(app/tools/mcp_client.py)

• 通用异步上下文管理器包装 mcp 开发包
• 管理 stdio_client + ClientSession 具有适当生命周期 __aenter__ / __aexit__
• 暴露： call_tool, list_tools, list_resources, read_resource
• 可以通过更改指向任何符合MCP的服务器 command 和 args

______________________________________________________________________

MCP的工作原理

模型上下文协议（MCP）是一个开放标准，用于通过stdio或HTTP上的JSON-RPC协议将AI助手连接到外部工具。

在本项目中：

1. MCPClient.__aenter__ 生成 npx -y @modelcontextprotocol/server-github 作为子流程
2. 通过进程stdin/stdout使用MCP有线协议进行通信
3. session.initialize() 完成握手
4. 工具调用通过 session.call_tool(tool_name, arguments)
5. GitHub MCP服务器通过 GITHUB_PERSONAL_ACCESS_TOKEN

此模式是可交换的——用任何其他服务器（文件系统、Jira、Slack、Notion等）替换GitHub MCP服务器，而无需接触代理逻辑。

______________________________________________________________________

项目结构

.
├── app/
│   ├── main.py             FastAPI app initialization and uvicorn entry point
│   ├── graph.py            LangGraph StateGraph definition and compilation
│   ├── state.py            AgentState TypedDict
│   ├── config.py           Environment config loaded via python-dotenv
│   ├── nodes/
│   │   ├── planner.py      GPT-4.1-mini intent extraction (returns structured JSON)
│   │   ├── router.py       Conditional routing logic
│   │   ├── executor.py     Concurrent tool execution via asyncio.gather
│   │   ├── synthesizer.py  GPT-4.1-mini response generation from tool outputs
│   │   └── finalizer.py    Output standardization
│   └── tools/
│       ├── web_search.py   DuckDuckGo search via ddgs library
│       ├── mcp_client.py   Generic async MCP client
│       └── github_tool.py  GitHub via MCP server (list, detail, summarize)
├── api/
│   └── routes.py           FastAPI route definitions (POST /chat, GET /health)
├── requirements.txt
├── .env.example            Template — copy to .env and fill values
└── README.md

______________________________________________________________________

设置

先决条件

• Python 3.12+
• 带npx的Node.js 18+（适用于GitHub MCP服务器）
• 可访问的OpenAI API密钥 gpt-4.1-mini
• GitHub个人访问令牌

安装

git clone 
cd Anthropic_MCP_Framework

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

pip install -r requirements.txt

配置

copy .env.example .env

打开 .env 并填写：

OPENAI_API_KEY=sk-...

GITHUB_USERNAME=your-github-username
GITHUB_TOKEN=ghp_...

GitHub令牌： → 生成新令牌（经典）→ 范围： repo, read:user

跑

python app/main.py

服务器启动时间 http://localhost:8000 Swagger用户界面位于 http://localhost:8000/docs

______________________________________________________________________

API 参考

POST/聊天

请求：

{
  "query": "string"
}

答复：

{
  "response": "string",
  "tools_used": ["web_search"],
  "metadata": {
    "intent": "web_search",
    "tools_failed": [],
    "planning_reasoning": "User is asking for recent information requiring a web search."
  }
}

GET/健康

{ "status": "ok", "service": "Nisarg Kadam Tech Handler" }

______________________________________________________________________

示例查询

网络搜索：

{ "query": "Search latest trends in agentic AI" }

GitHub——列出所有仓库：

{ "query": "List all my GitHub repositories" }

GitHub——仓库详细信息：

{ "query": "Explain my GitHub repository called nlp-pipeline" }

GitHub——技术栈：

{ "query": "What is the tech stack of my repo called ai-automation?" }

多意图：

{ "query": "Search for LangGraph best practices and also summarize my GitHub repos" }

直接（无工具）：

{ "query": "What is the difference between LangChain and LangGraph?" }

______________________________________________________________________

环境变量