Agent MCP Notion GitHub

MCP代理-Notion和GitHub集成

智能代理通过MCP（模型上下文协议）服务器连接到Notion和GitHub，通过交叉引用文档和代码提供上下文答案。

特性

• 概念整合：搜索和查询Notion页面、数据库和内容
• GitHub集成：通过GitHub API访问存储库、提交、代码和问题
• AI推理：使用OpenAI关联信息并提供智能答案
• 现代堆栈：Django+React+惯性.js与TypeScript

快速开始

先决条件

• Python 3.12+
• Node.js 20+
• Docker和Docker Compose（可选）
• OpenAI API密钥
• GitHub个人访问令牌（用于GitHub集成）
• Notion内部集成令牌（用于Notion集成）

地方发展

1. 克隆和设置环境:

cp .env_example .env
# Edit .env with your API keys

1. 后端设置:

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

1. 前端设置:

cd frontend
npm install
npm run build

1. 访问：打开http://localhost:8000

Docker设置

docker compose up --build

然后打开http://localhost:8000

配置

创建一个 .env 项目根目录中的文件：

# OpenAI API Key (required)
OPENAI_API_KEY=sk-your-key-here

# Notion MCP Server
NOTION_MCP_CMD=python agent/notion_mcp_server.py --token ntn_your_notion_token
NOTION_TOKEN=ntn_your_notion_token

# GitHub MCP Server (uses Docker)
GIT_MCP_CMD=docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token ghcr.io/github/github-mcp-server
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token

# Optional: Notion root page IDs (comma-separated)
NOTION_ROOT_IDS=

# Django Settings
DEBUG=true
SECRET_KEY=your-secret-key-here

获取API密钥

OpenAI API密钥:

1. 首选https://platform.openai.com/api-keys
2. 创建新的API密钥
3. 复制并添加到 .env

GitHub个人访问令牌:

1. 首选https://github.com/settings/tokens
2. 使用生成新令牌（经典） repo 范围
3. 复制令牌（以开头 ghp_)并添加到 .env

Notion内部集成令牌:

1. 首选https://www.notion.so/my-integrations
2. 创建新的集成
3. 复制令牌（以开头 ntn_)并添加到 .env
4. 通过集成共享您的Notion页面/数据库

项目结构

backend/
  ├── agent/          # MCP client, reasoning, and Notion MCP server
  ├── api/            # REST API endpoints
  ├── core/           # Django settings
  └── web/            # Inertia views

frontend/
  ├── src/
  │   └── pages/     # React components
  └── dist/          # Built assets

API终点

• GET / -聊天界面
• GET /api/health/mcp -MCP服务器健康检查
• POST /api/agent/query -自然语言查询代理

运作原理

1. 查询解析：使用OpenAI解析自然语言查询并提取优化的搜索词
2. MCP集成：通过stdio连接到Notion和GitHub MCP服务器
3. 数据检索：同时搜索Notion页面和GitHub存储库
4. AI相关性：使用OpenAI将结果关联起来，并提供带有引用的上下文答案
5. 响应：返回包含源引用的摘要

故障排除

MCP服务器未连接:

• 检查运行状况端点： curl http://localhost:8000/api/health/mcp
• 验证中的环境变量 .env
• 检查Docker是否正在运行（适用于GitHub MCP服务器）
• 查看后端日志中的连接错误

概念身份验证:

• 确保 NOTION_TOKEN 设置正确
• 验证集成是否可以访问您的Notion页面
• 检查令牌格式（应以开头 ntn_)

GitHub身份验证:

• 验证 GITHUB_PERSONAL_ACCESS_TOKEN 有效
• 确保令牌具有 repo 范围
• 检查Docker套接字是否已挂载（用于Docker设置）

工作流程图

alt text