Spicedb MCP Server

SpiceDB MCP服务器

\[！小心\] 这是一个实验性的MCP服务器。这仅用于教育目的，因此使用风险由您自行承担。

连接到的模型上下文协议（MCP）服务器 SpiceDB 通过其用于权限管理的HTTP API。此服务器使Claude等LLM能够与您的SpiceDB实例交互，以查询、管理和理解您的权限系统。

特性

\[！注意\] 这个repo中的所有内容几乎都是由Claude 3.5 Sonnet创建的。任何怪癖、异常模式或潜在错误都是基于LLM的生成的直接产物。

• 资源:

- 使用关联的对象定义资源进行模式检索 - 使用交互式关系资源进行关系查询 - 具有详细类型信息的对象定义

• 工具:

- 使用对象定义资源读取架构 - 使用关系资源读取关系 - 通过详细的授权跟踪和解释检查权限 - 按主题和权限上下文查找资源 - 按资源查找具有权限详细信息的主题 - 编写带有验证的关系

先决条件

• Node.js 16+
• SpiceDB实例
• SpiceDB API密钥

安装

1. 克隆此存储库：

   git clone https://github.com/authzed/spicedb-mcp-server.git
   cd spicedb-mcp-server

1. 安装依赖项：

   npm install
   # or
   yarn install

1. 配置您的环境：

创建一个 .env 包含您的SpiceDB连接详细信息的文件：

   # SpiceDB HTTP API endpoint (the default port for HTTP API is typically 8443)
   SPICEDB_ENDPOINT=http://localhost:8443
   # or for TLS: https://spicedb.example.com

   SPICEDB_API_KEY=your-api-key-here
   SPICEDB_USE_TLS=false

1. 构建服务器：

   npm run build
   # or
   yarn build

用法

直接运行

从命令行运行服务器：

node build/index.js
# or
npm start
# or
yarn start

与Claude for Desktop集成

1. 编辑您的Claude for Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

1. 将SpiceDB MCP服务器添加到 mcpServers 章节：

{
  "mcpServers": {
    "spicedb": {
      "command": "node",
      "args": [
        "/path/to/spicedb-mcp-server/build/index.js"
      ],
      "env": {
        "SPICEDB_ENDPOINT": "http://localhost:8443",
        "SPICEDB_API_KEY": "your-api-key-here",
        "SPICEDB_USE_TLS": "false"
      }
    }
  }
}

1. 重新启动桌面版的Claude

1. 查看Claude Desktop和SpiceDB MCP的日志

macOS: /Users//Library/Logs/Claude/mcp-server-spicedb.log 和 /Users//Library/Logs/Claude/mcp.log

例子

\[！注意\] 带有模式和关系数据的SpiceDB实例应使用该标志运行 --http-enabled

Claude的命令示例

检查权限：

“user:alice是否具有document:report1的权限视图？”

查找受试者可以访问的所有资源：

用户bob可以阅读哪些文档

查找可以访问资源的所有主题：

“谁有项目网站的编辑权限？”

分析架构：

“你能解释一下权限系统架构吗？”

设置测试场景

通过编写适当的关系设置以下场景：有一个新角色“审核员”，用户jared具有该角色

预览合规操作

“pied_piper项目现已弃用。查找所有具有某种访问权限的用户，并创建一个全面的用户及其访问权限列表”

api参考

资源

• spicedb://schema -获取当前模式，返回模式文本和对象定义资源
• spicedb://relationships/{resourceType?}/{resourceId?}/{relation?}/{subjectType?}/{subjectId?}/{subjectRelation?} -使用可选筛选器查询关系
• spicedb://definition/{objectType} -获取特定对象类型的详细定义

工具

• read-schema -使用对象定义资源检索当前架构
• read-relationships -基于筛选器参数查询关系，返回文本输出和关系资源
• check-permission -通过调试跟踪和授权决策的解释检查主题是否对资源具有特定权限
• lookup-resources -查找主题具有特定权限的资源，针对数组响应格式进行了优化
• lookup-subjects -查找对资源具有特定权限的主题，针对数组响应格式进行了优化
• write-relationship -通过验证创建、更新或删除关系

鼓励

• lookup-resources-for-subject -查找主题可以访问的资源
• lookup-subjects-for-resource -查找可以访问资源的主题
• explain-permission-check -解释权限检查结果
• analyze-schema -分析当前权限架构

关系格式

SpiceDB中的关系格式为：

resourceType:resourceId#relation@subjectType:subjectId[#subjectRelation]

此格式结合了：

• 资源： resourceType:resourceId （正在访问的对象）
• 关系： #relation （关系类型）
• 主题： subjectType:subjectId （访问资源的参与者）
• 可选主题关系： #subjectRelation （适用于计算机科目）

示例：

• document:report#viewer@user:alice -用户alice是报告文档的查看器
• project:website#admin@group:engineering#member -工程组的成员是网站项目的管理员
• resource:promserver#viewer@usergroup:engineering#member -工程用户组的成员是promserver资源的查看者

MCP连接生命周期

SpiceDB MCP服务器实现了完整的模型上下文协议连接生命周期：

1. 初始化请求：当客户端连接时，它会发送 initialize 请求包含：

- 协议版本 - 客户信息（名称、版本） - 客户端功能

1. 服务器响应：服务器响应：

- 协议版本 - 服务器信息（名称、版本） - 服务器功能（资源、工具、提示等）

1. 初始化确认：客户端发送 initialized 通知以确认连接。

1. 消息交换：正常操作始于请求和响应的交换。

1. 终止：当客户端断开连接时，服务器会清理资源。

服务器将此生命周期的详细信息记录到stderr中，您可以在直接运行服务器时观察到。

服务器功能

此服务器提供以下功能：

• 资源：将模式、关系和定义作为可读和可导航的资源公开
• 工具：提供与SpiceDB交互的工具，并提供丰富的响应，包括资源
• 鼓励：为常见的权限相关任务和分析提供模板提示
• 调试跟踪：包括详细的授权决策跟踪和解释
• 响应格式：支持传统和基于阵列的SpiceDB API响应格式
• 日志记录：为故障排除和监控提供结构化日志记录