Stardog MCP Server

Stardog MCP 服务

一个与 Stardog 服务 API 交互的 MCP 服务实现，可为开发者和工具提供自动化与交互能力。

https://github.com/user-attachments/assets/4a41d6fb-8b20-4994-b973-81ce1c10c04a

警告

这是一个正在开发中的项目，内容可能会发生重大变化。

注意

使用任何 MCP 服务时都请谨慎。此 MCP 服务会向 Stardog 服务发送请求，并且可能会修改数据或配置。如果想限制对数据的修改，可以提供只读用户或权限受限用户的凭据。

开始使用

将代码库克隆到本地计算机。记下克隆后的代码库路径，稍后会用到。

$ pwd
/Users/noah/projects/mcp-server-stardog

通用先决条件

• 已安装 uv。

说明

如果计划将 MCP 与 Claude Desktop 或其他兼容 MCP 的客户端搭配使用，则需要安装该客户端。

Stardog 先决条件

你需要凭据才能访问正在运行的 Stardog 服务。

$ curl -i -u anonymous:anonymous https://express.stardog.cloud:5820/admin/status/whoami
HTTP/2 200
date: Wed, 16 Apr 2025 20:46:50 GMT
content-length: 9

anonymous

在 VS Code 中使用

将以下 JSON 代码块添加到 VS Code 中的 User Settings (JSON) 文件。你可以按 Ctrl + Shift + P 并输入 Preferences: Open User Settings (JSON) 来执行此操作。

 "mcp": {
        "servers": {
            "stardog": {
                "type": "stdio",
                "command": "uv",
                "args": [
                    "--directory",
                    "/Users/noah/projects/mcp-server-stardog",
                    "run",
                    "mcp-server-stardog"
                ],
                "env": {
                    "SD_USERNAME": "${env:SD_USERNAME}",
                    "SD_PASSWORD": "${env:SD_PASSWORD}",
                    "SD_ENDPOINT": "${env:SD_ENDPOINT}"
                },
            }
        }
    }

你需要为 uv 的 --directory 选项提供此代码库的克隆路径。VS Code 会传入 SD_USERNAME、SD_PASSWORD 和 SD_ENDPOINT 环境变量，供 MCP 服务使用。设置这些环境变量后，你可能需要重启 VS Code 才能使其读取到这些变量。

说明

关于在 VS Code 中使用 MCP 服务工具的更多信息，请参阅 Agent 模式文档。

你也可以使用 --endpoint、--username 和 --password 命令行选项直接在配置中设置这些值。

 "mcp": {
        "servers": {
            "stardog": {
                "type": "stdio",
                "command": "uv",
                "args": [
                    "--directory",
                    "/Users/noah/projects/mcp-server-stardog",
                    "run",
                    "mcp-server-stardog",
                    "--endpoint",
                    "https://express.stardog.cloud:5820",
                    "--username",
                    "anonymous",
                    "--password",
                    "anonymous"
                ]
            }
        }
    }

说明

你也可以使用令牌向 Stardog 服务进行身份验证。可以在 SD_AUTH_TOKEN 环境变量中设置令牌，也可以使用 --auth-token 命令行参数。如果同时提供令牌和用户名、密码，则会使用令牌。

在 Claude Desktop 中使用

1. 如果尚未安装 Claude Desktop，请从 https://claude.ai/download 下载。
2. 打开 Claude Desktop 配置文件。
   • 若要快速找到配置文件，或首次创建该文件，请打开 Claude Desktop 应用，选择 Settings，然后点击 Developer 选项卡。最后，点击 Edit Config 按钮。
   • 将以下配置添加到文件中，并将 username、password 和 endpoint 替换为你自己的值：

{
    "mcpServers": {
        "stardog": {
            "command": "/Users/noah/.local/bin/uv",
            "args": [
                "--directory",
		"/Users/noah/projects/mcp-server-stardog",
                "run",
                "mcp-server-stardog"
                "--endpoint",
                "https://express.stardog.cloud:5820",
                "--username",
                "anonymous",
                "--password",
                "anonymous",
                "--auth-token",
                "your_auth_token"
            ],
        }
    }
}

说明

你可以使用用户名和密码或身份验证令牌向 Stardog 进行身份验证。如果同时提供两者，则会使用身份验证令牌。username、password 和 auth_token 选项不能同时使用。

提示

你可以运行 which uv 来查找 uv 命令的路径。配置中的 command 字段应使用此路径。

$ which uv
/Users/noah/.local/bin/uv

你也可以使用环境变量设置 username、password、auth_token 和 endpoint 选项。环境变量如下：

• SD_USERNAME
• SD_PASSWORD
• SD_AUTH_TOKEN
• SD_ENDPOINT

在 Claude Desktop 中，你可以在配置中提供 env 对象来设置这些环境变量。例如：

{
    "mcpServers": {
        "stardog": {
            "command": "/Users/noah/.local/bin/uv",
            "args": [
                "--directory",
        "/Users/noah/projects/mcp-server-stardog",
                "run",
                "mcp-server-stardog"
            ],
            "env": {
                "SD_USERNAME": "anonymous",
                "SD_PASSWORD": "anonymous",
                "SD_ENDPOINT": "https://express.stardog.cloud:5820"
            }
        }
    }
}

工具

数据库

• list_databases - 列出 Stardog 服务中的所有 Stardog 数据库。
  • 无需参数。
• get_database_size - 获取 Stardog 数据库的估算大小（以三元组计）。
  • database_name (string, required)：Stardog 数据库的名称。
• get_database_configuration - 获取 Stardog 数据库的配置。可选按特定键筛选。
  • database_name (string, required)：Stardog 数据库的名称。
  • option_keys (string[], optional)：用于筛选配置的特定数据库选项键列表。
• get_database_configuration_documentation - 获取 Stardog 数据库配置选项的文档。
  • 无需参数。

查询

• execute_sparql_read - 执行 SPARQL 读取查询。支持 SELECT、CONSTRUCT、DESCRIBE 和 ASK 查询。

  • query (string, required)：要执行的 SPARQL 查询
  • database (string, required)：要执行查询的数据库。
  • query_type (string, optional)：查询类型。可接受的值为 select、construct、describe 和 ask。默认值为 select。
  • reasoning (boolean, optional)：执行查询时是否启用推理。默认值为 false。
  • schema (string, optional)：执行查询时使用的推理模式。默认值为 default。
  • limit (int, optional)：查询结果的限制数量。默认值为 1000。如果 LLM 的上下文长度有限，此参数可能会有帮助。
  • timeout_ms (int, optional)：查询超时时间（毫秒）。默认值为 30000（30 秒）。

• list_stored_queries - 列出 Stardog 服务中的所有已存储查询。

  • 无需参数。

监控

• list_processes - 列出 Stardog 服务上运行的所有进程。
  • 无需参数。
• kill_process - 终止 Stardog 服务上运行的指定进程。
  • id (string, required)：要终止的进程 ID。
• get_server_metrics - 获取 Stardog 服务的服务器指标。
  • 无需参数。

角色

• list_roles - 列出 Stardog 服务中的所有角色。可选择包含权限，也可筛选结果，仅显示指定的角色。
  • include_permissions（boolean，可选）：是否包含分配给角色的权限。
  • roles_filter（string[]，可选）：用于筛选结果的角色名称列表。
• get_users_with_role - 列出分配了某个角色的用户名称
  • role_name：（string，必填）：角色名称
• create_role - 在 Stardog 服务中创建新角色。
  • role_name（string，必填）：要创建的角色名称。
• assign_role_to_user - 将角色分配给指定用户。
  • role_name（string，必填）：角色名称。
  • username（string，必填）：用户的用户名。
• revoke_role_from_user - 撤销指定用户的角色。
  • role_name（string，必填）：角色名称。
  • username（string，必填）：用户的用户名。
• assign_permission_to_role - 为指定角色分配权限。
  • role_name（string，必填）：角色名称。
  • permission（object，必填）：要分配给角色的权限。权限对象应包含以下字段：
    • action（string，必填）：要分配的操作（例如 read、write 等）
    • resource_type（string，必填）：资源类型（例如 db、user、role 等）
    • resource（字符串数组，必填）：要为其分配权限的资源（例如数据库名称、用户名、角色名称、* 等）
• revoke_permission_from_role - 撤销指定角色的权限。
  • role_name（string，必填）：角色名称。
  • permission（object，必填）：要从角色撤销的权限。权限对象应包含以下字段：
    • action（string，必填）：要分配的操作（例如 read、write 等）
    • resource_type（string，必填）：资源类型（例如 db、user、role 等）
    • resource（字符串数组，必填）：要为其分配权限的资源（例如数据库名称、用户名、角色名称、* 等）
• delete_role - 从 Stardog 服务中删除角色。
  • role_name（string，必填）：要删除的角色名称。
  • force（boolean，可选）：强制删除角色（即使仍分配给用户也删除）。默认值为 false。

用户

• list_users - 列出 Stardog 服务中的所有用户。可选择包含权限、超级用户状态和活跃状态等详细信息。
  • include_details（boolean，可选）：是否包含用户的详细信息。
  • usernames_filter（string[]，可选）：用于筛选结果的用户名列表。
• get_roles_assigned_to_user - 获取分配给指定用户的角色。
  • username（string，必填）：用户的用户名。
• assign_permission_to_user - 为指定用户分配权限。
  • username（string，必填）：用户的用户名。
  • permission（object，必填）：要分配给用户的权限。权限对象应包含以下字段：
    • action（string，必填）：要分配的操作（例如 read、write 等）
    • resource_type（string，必填）：资源类型（例如 db、user、role 等）
    • resource（字符串数组，必填）：要为其分配权限的资源（例如数据库名称、用户名、角色名称、* 等）
• revoke_permission_from_user - 撤销指定用户的权限。
  • username（string，必填）：用户的用户名。
  • permission（object，必填）：要从用户撤销的权限。权限对象应包含以下字段：
    • action（string，必填）：要分配的操作（例如 read、write 等）
    • resource_type（string，必填）：资源类型（例如 db、user、role 等）
    • resource（字符串数组，必填）：要为其分配权限的资源（例如数据库名称、用户名、角色名称、* 等）

身份验证

• get_whoami - 获取当前已通过身份验证的用户信息。
  • 无需参数。

提示词

说明

包括 VS Code 在内的部分 MCP 客户端尚不支持提示词。Claude Desktop 支持提示词。

• database_config_helper - 分析 Stardog 数据库的配置并生成详细报告。

  • database_name（string，必填）：Stardog 数据库的名称。
  • option_keys（string，必填）：以逗号分隔的特定数据库选项键列表，用于筛选配置。

• roles_summary - 汇总 Stardog 服务中的角色及其权限。

  • 无需参数。