内容
# SCINR 图形服务
[](https://opensource.org/licenses/Apache-2.0)
> SCINR 是首个为生命科学行业打造的 AI 原生供应链自主调度平台。它在供应链的每个环节都嵌入了 AI，实现主数据调度、持续规划和自我修复的弹性，帮助制药和生物技术公司预防药品短缺、加速上市时间并保持完全的监管合规。更多信息请访问 [scinr.com](https://www.scinr.com/)。
**SCINR 图形服务** 是一个 FastAPI 微服务，通过 REST API 和集成的 **MCP（模型上下文协议）服务器**公开 Neo4j 图形数据库的读取操作。它是 SCINR 平台的核心组件，使 AI 代理和外部客户端能够安全高效地查询供应链知识图谱。
---
## 📋 目录
- [技术栈](#-tech-stack)
- [前提条件](#-prerequisites)
- [项目结构](#-project-structure)
- [安装](#-installation)
- [环境变量](#-environment-variables)
- [PYTHONPATH 配置](#-pythonpath-configuration)
- [运行服务](#-running-the-service)
- [API 端点](#-api-endpoints)
- [MCP 集成](#-mcp-integration)
- [架构说明](#-architecture-notes)
- [许可证](#license)
---
## 🛠 技术栈
| 组件 | 版本 |
|---|---|
| Python | ≥ 3.14 |
| FastAPI | 最新版本 |
| `fastmcp` | ≥ 3.2.4 |
| `neo4j` Python 驱动程序 | ≥ 6.2.0 |
| `uvicorn` | ASGI 服务器 |
| `uv` | 推荐的包管理器 |
---
## ✅ 前提条件
- **Python 3.14+**
- **`uv`** （推荐的包管理器 — [安装指南](https://docs.astral.sh/uv/getting-started/installation/)）
- 一个 **Neo4j 数据库实例**，并安装和启用 **APOC 插件**（`/schema` 端点所需）
---
## 📁 项目结构
```
graphApi/
├── src/
│ ├── main.py # 应用入口点，FastAPI + MCP 设置
│ ├── api/
│ │ └── graphApiRouter.py # 公共 REST API 路由
│ ├── mcp_servers/
│ │ └── graphMcp.py # FastMCP 服务器定义和工具
│ ├── models/
│ │ └── graphModels.py # Pydantic 请求/响应模型
│ └── utils/
│ └── neo4jUtils.py # Neo4j 驱动程序和查询助手
├── pyproject.toml
├── uv.lock
└── .env
```
---
## 🚀 安装
### 使用 `uv` （推荐）
1. **克隆仓库**
```bash
git clone <仓库网址>
cd graphApi
```
2. **创建虚拟环境**
```bash
uv venv
```
3. **激活虚拟环境**
| 平台 | 命令 |
|---|---|
| Linux / macOS | `source .venv/bin/activate` |
| Windows CMD | `.venv\Scripts\activate` |
| Windows PowerShell | `.venv\Scripts\Activate.ps1` |
4. **安装依赖项**
```bash
uv sync
```
---
## 🔐 环境变量
在项目根目录下创建 `.env` 文件，并包含以下变量：
```dotenv
NEO4J_URI=neo4j+s://xxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
```
| 变量 | 描述 | 示例 |
|---|---|---|
| `NEO4J_URI` | Neo4j 实例的连接 URI | `neo4j+s://xxxx.databases.neo4j.io` |
| `NEO4J_USERNAME` | Neo4j 数据库用户名 | `neo4j` |
| `NEO4J_PASSWORD` | Neo4j 数据库密码 | `your_password` |
> ⚠️ **不要提交您的 `.env` 文件。** 它已经列在 `.gitignore` 中。
---
## 🐍 PYTHONPATH 配置
在运行应用程序之前，将 `PYTHONPATH` 环境变量设置为 `src/`，以便 Python 可以正确解析内部模块导入。
```bash
# Linux / macOS
export PYTHONPATH=src/
# Windows CMD
set PYTHONPATH=src\
# Windows PowerShell
$env:PYTHONPATH="src/"
```
---
## ▶️ 运行服务
配置环境变量和 `PYTHONPATH` 后，使用以下命令启动服务：
```bash
uvicorn src.main:app --host 0.0.0.0 --port 8000
```
| 资源 | URL |
|---|---|
| REST API | `http://localhost:8000` |
| Swagger UI（交互式文档） | `http://localhost:8000/docs` |
| MCP 服务器 | `http://localhost:8000/mcp` |
---
## 📡 API 端点
| 方法 | 路径 | 描述 | 访问权限 |
|---|---|---|---|
| `GET` | `/` | 健康检查 | 公共 |
| `GET` | `/api/graph/schema` | 检索完整的 Neo4j 图形模式（需要 APOC 插件） | 公共 |
| `POST` | `/api/graph/read` | 对数据库执行 Cypher 读取查询 | 公共 |
### `POST /api/graph/read` — 请求体
```json
{
"query": "MATCH (n:Person) RETURN n LIMIT 10",
"params": {}
}
```
> ⚠️ **仅允许读取查询。** 在数据库级别明确阻止写入操作（`MERGE`、`CREATE`、`SET`、`DELETE` 等）。
---
## 🤖 MCP 集成
该服务嵌入了一个由 [`fastmcp`](https://github.com/jlowin/fastmcp) 驱动的 **模型上下文协议（MCP）服务器**。MCP 服务器安装在 `/mcp` 上，并使用**无状态 HTTP 传输**（`stateless_http=True`），使其与无服务器部署（例如 AWS Lambda）完全兼容，在这些部署中，请求之间不维护持久的会话状态。
### 可用的 MCP 工具
| 工具 | 描述 |
|---|---|
| `get_schema` | 列出数据库中的所有节点、属性和关系 |
| `read_neo4j_cypher` | 执行 Cypher 读取查询并返回结果 |
### 连接 MCP 客户端
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"scinr-graph": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
**Cursor** — 添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"scinr-graph": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
---
## 🏗 架构说明
- **反向代理**：应用程序配置为 `root_path="/graphApi"`，这意味着它设计为在反向代理后面运行，该代理在该路径前缀下转发请求。
- **CORS**：默认情况下，跨源资源共享（CORS）启用 `http://localhost:3000` 和 `http://localhost:8000`。更新 `src/main.py` 中的 `origins` 以匹配您的前端或客户端 URL。
- **MCP 无状态传输**：MCP 服务器使用 `stateless_http=True`，这意味着每个请求都是完全独立的，没有服务器端会话状态。这对于无服务器部署（例如 AWS Lambda）是必需的，在这些部署中，进程可能在调用之间被回收。MCP 工具直接在进程中调用 REST 处理函数 — 没有内部 HTTP 往返。
- **只读**：该服务仅对 Neo4j 数据库执行读取操作。在数据库级别明确阻止写入查询。
---
## 许可证
该项目在 **Apache License 2.0** 下获得许可 — 有关详细信息，请参阅 [LICENSE](./LICENSE) 文件。
Copyright 2026 SCINR
[](https://opensource.org/licenses/Apache-2.0)
---
<p align="center">
使用 ❤️ 为 SCINR 平台构建 — <a href="https://www.scinr.com/">scinr.com</a>
</p>
