内容
# RDF4J MCP 服务器
**使用 Claude 探索知识图谱** - 一个模型上下文协议（MCP）服务器，能够实现对 RDF 数据和 SPARQL 查询的 AI 驱动探索。
## 快速演示
在 2 分钟内试用：
```bash
# 1. 克隆并安装
git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync # 或：pip install -e .
# 2. 启动 RDF4J + 加载示例数据
./examples/setup-demo.sh
# 3a. 作为本地 MCP 服务器运行（stdio）
rdf4j-mcp --server-url http://localhost:8081/rdf4j-server --repository demo
# 3b. 或作为远程 HTTP 服务器运行
rdf4j-mcp-server --port 3000 --server-url http://localhost:8081/rdf4j-server --repository demo
```
然后使用以下提示与 Claude 交互：
> "知识图谱中有哪些类和属性？"
> "查找所有人员及其正在进行的项目"
> "显示预算最高的项目"
## 安装
**先决条件：** Python 3.11+，Docker（用于 RDF4J）
```bash
git clone https://github.com/your-org/rdf4j-mcp.git
cd rdf4j-mcp
uv sync # 或：pip install -e .
```
## 两种运行方式
| 命令 | 传输方式 | 用例 |
|---------|-----------|----------|
| `rdf4j-mcp` | stdio | MCP 客户端在本地启动（Claude Desktop，VS Code） |
| `rdf4j-mcp-server` | HTTP/SSE | 独立远程服务器，多个客户端 |
### 选项 1：本地模式（stdio）
MCP 客户端将服务器作为本地进程启动：
```bash
rdf4j-mcp --server-url http://localhost:8080/rdf4j-server --repository my-repo
```
### 选项 2：远程模式（HTTP/SSE）
作为独立的 HTTP 服务器运行：
```bash
# 启动服务器
rdf4j-mcp-server --port 3000 \
--server-url http://localhost:8080/rdf4j-server \
--repository my-repo
# 或使用环境变量
export RDF4J_MCP_RDF4J_SERVER_URL=http://localhost:8080/rdf4j-server
export RDF4J_MCP_DEFAULT_REPOSITORY=my-repo
rdf4j-mcp-server --port 3000
# 或使用 uvicorn（生产环境）
uvicorn rdf4j_mcp.main:app --host 0.0.0.0 --port 3000 --workers 4
```
**端点：**
- `GET /sse` - MCP 客户端的 SSE 端点
- `GET /health` - 健康检查
- `GET /info` - 服务器配置
## 客户端配置
### Claude Desktop
配置文件位置：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- Linux：`~/.config/Claude/claude_desktop_config.json`
**本地模式（stdio）：**
```json
{
"mcpServers": {
"rdf4j": {
"command": "rdf4j-mcp",
"args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
}
}
}
```
**远程模式（HTTP）：**
```json
{
"mcpServers": {
"rdf4j": {
"url": "http://your-server:3000/sse"
}
}
}
```
### VS Code
在工作空间中创建 `.vscode/mcp.json`：
**本地模式：**
```json
{
"servers": {
"rdf4j": {
"command": "rdf4j-mcp",
"args": ["--server-url", "http://localhost:8080/rdf4j-server", "--repository", "my-repo"]
}
}
}
```
**远程模式：**
```json
{
"servers": {
"rdf4j": {
"url": "http://your-server:3000/sse"
}
}
}
```
对于 GitHub Copilot，在聊天中使用 `@mcp`：
```
@mcp 知识图谱中有哪些类？
```
## 功能
### MCP 工具
| 工具 | 描述 |
|------|-------------|
| `sparql_select` | 执行 SELECT 查询，返回 JSON |
| `sparql_construct` | 执行 CONSTRUCT/DESCRIBE，返回 Turtle |
| `sparql_ask` | 执行 ASK 查询，返回布尔值 |
| `describe_resource` | 获取关于 IRI 的所有三元组 |
| `search_classes` | 按名称模式查找类 |
| `search_properties` | 按模式/域/范围查找属性 |
| `find_instances` | 查找类的实例 |
| `get_schema_summary` | 具有统计信息的本体论概述 |
| `list_repositories` | 列出可用的存储库 |
| `get_namespaces` | 获取命名空间前缀映射 |
| `get_statistics` | 语句/类/属性计数 |
| `select_repository` | 切换活动存储库 |
### MCP 资源
| URI | 描述 |
|-----|-------------|
| `rdf4j://repositories` | 存储库列表 |
| `rdf4j://repository/{id}/schema` | 模式摘要 |
| `rdf4j://repository/{id}/namespaces` | 命名空间前缀 |
| `rdf4j://repository/{id}/statistics` | 存储库统计信息 |
### MCP 提示
| 提示 | 描述 |
|--------|-------------|
| `explore_knowledge_graph` | 具有模式上下文的引导式探索 |
| `write_sparql_query` | 自然语言到 SPARQL |
| `explain_ontology` | 解释类和关系 |
## 配置
### CLI 选项
**rdf4j-mcp（stdio 模式）：**
```
--server-url URL RDF4J 服务器 URL（默认：http://localhost:8080/rdf4j-server）
--repository ID 默认存储库 ID
--debug 启用调试日志记录
```
**rdf4j-mcp-server（HTTP 模式）：**
```
--host HOST 绑定地址（默认：0.0.0.0）
--port PORT 监听端口（默认：3000）
--server-url URL RDF4J 服务器 URL
--repository ID 默认存储库 ID
--reload 开发环境下的自动重载
--debug 启用调试日志记录
```
### 环境变量
所有变量均使用 `RDF4J_MCP_` 前缀：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `RDF4J_SERVER_URL` | `http://localhost:8080/rdf4j-server` | RDF4J 服务器 URL |
| `DEFAULT_REPOSITORY` | - | 默认存储库 ID |
| `QUERY_TIMEOUT` | `30` | 查询超时（秒） |
| `DEFAULT_LIMIT` | `100` | 默认查询 LIMIT |
| `MAX_LIMIT` | `10000` | 最大查询 LIMIT |
## 运行 RDF4J 服务器
使用 Docker：
```bash
docker run -d -p 8080:8080 eclipse/rdf4j-workbench
```
然后在 http://localhost:8080/rdf4j-workbench 上创建一个存储库。
或使用演示设置脚本来处理所有内容：
```bash
./examples/setup-demo.sh
```
## 开发
```bash
uv sync --dev
# 运行测试
pytest
# 校验和格式化
ruff check src tests
ruff format src tests
# 类型检查
ty check src
```
## 许可证
MIT
