magicsword-mcp

magicsword-mcp

面向 MagicSword 的 Model Context Protocol 服务。 使用 Claude Desktop、Cursor 或任何支持 MCP 的客户端的用户，都可以通过对话管理 MagicSword——列出端点、查询警报、分类调查结果、创建注册令牌，以及预览 / 提交策略更改。

该服务是对 Magic Portal 提供的 /api/public/v1/* 客户 API 的轻量封装，并带有明确的使用主张。它在用户的计算机上运行，持有 msk_… API 密钥，并通过标准输入/输出使用 MCP。

计划限制。 客户 API 仅面向 Enterprise 计划。使用试用版密钥时，服务会返回明确消息：“此 MagicSword 组织需要 Enterprise 计划才能使用 MCP”；组织升级前，其他功能均不可用。

快速开始

Claude Desktop 安装程序

对于 macOS 或 Windows 上的 Claude Desktop，请从 GitHub Releases 下载 magicsword-mcp.mcpb。从 0.1.4 版开始，安装程序已包含在发布包中。如果该版本尚不可用，请使用下方的终端安装方式。

1. 在 Magic Portal → Settings → API Keys 中生成 Enterprise API 密钥。 首先为端点、警报和策略启用读取权限范围。
2. 在 Claude Desktop 中，打开 Settings → Extensions → Advanced settings → Install Extension…，然后选择下载的 .mcpb 文件。
3. 检查扩展，并在其安全配置字段中输入 API 密钥。Claude 会使用操作系统的安全存储来保存此敏感字段。安装程序不会另外保存 MagicSword 密钥文件。
4. 开始新对话，然后让 MagicSword 依次调用 whoami 和 list_endpoints。确认组织和权限范围。

安装程序包含服务及生产依赖项，并使用 Claude Desktop 内置的 Node 运行时（22+）。无需安装 npm，也无需编辑 JSON。安装程序旁边会发布其 SHA256 校验和。私下下载的扩展必须通过安装较新的 .mcpb 文件进行更新；自动目录更新则需要经过审核的目录列表。

终端安装

需要 Node.js 22+、已安装的 MCP 客户端，以及在 Magic Portal → Settings → API Keys 中生成的 MagicSword Enterprise API 密钥。

推荐：使用一条命令安装并连接客户端。 设置过程会私密地提示输入密钥，并让你选择 Claude Desktop、Codex、Claude Code 或 Cursor：

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure

已经确定要使用哪个客户端？运行对应的一行命令：

客户端	安装并配置
Claude Desktop	npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client claude-desktop
Cursor	npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client cursor
Claude Code	npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client claude-code
OpenAI Codex	npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client codex

更喜欢使用客户端自己的注册命令？在本地保存密钥后，无需全局安装服务也可以使用以下命令：

codex mcp add magicsword --env MAGICSWORD_BASE_URL=https://www.magicsword.io -- npx -y @magicsword-io/magicsword-mcp
claude mcp add --scope user --transport stdio magicsword --env MAGICSWORD_BASE_URL=https://www.magicsword.io -- npx -y @magicsword-io/magicsword-mcp

如果自动注册无法在 Windows 上启动客户端的 CLI，这些命令也可作为备用方案。桌面端启动仍要求客户端能够使用 Node/npx；推荐的设置方式使用绝对路径。

安装按钮：Cursor 和 VS Code

首先在本地保存你的 API 密钥（每台机器只需保存一次）：

npm install -g @magicsword-io/magicsword-mcp && magicsword-mcp configure --client manual

然后点击对应客户端的按钮，并批准其安装提示：

这些按钮会注册一个指向生产环境的本地 npx 服务。它们不包含 API 密钥；服务会读取 ~/.magicsword/mcp.json。客户端的 PATH 中必须有 npx。如果桌面应用找不到 Node 或 npx，请使用上文推荐的设置方式指定 绝对启动路径，或将 configure --client manual 打印的绝对 command 和 args 复制到其配置中。

手动 JSON 备用配置

在上方保存密钥后，将此条目合并到 Claude Desktop 的 claude_desktop_config.json 或 Cursor 的 ~/.cursor/mcp.json 中，并保留 其他服务：

{
  "mcpServers": {
    "magicsword": {
      "command": "npx",
      "args": [
        "-y",
        "@magicsword-io/magicsword-mcp"
      ],
      "env": {
        "MAGICSWORD_BASE_URL": "https://www.magicsword.io"
      }
    }
  }
}

对于 VS Code / Insiders，运行 MCP: Open User Configuration 并合并此 配置（VS Code 使用 servers，而非 mcpServers）：

{
  "servers": {
    "magicsword": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@magicsword-io/magicsword-mcp"
      ],
      "env": {
        "MAGICSWORD_BASE_URL": "https://www.magicsword.io"
      }
    }
  }
}

重启客户端或开始新会话，然后让它调用 whoami 和 list_endpoints。两者都必须成功，才能验证身份验证和读取权限。

官方 MCP Registry 标识符为 io.github.magicsword-io/magicsword-mcp。下文将介绍各客户端的具体配置。

配置

magicsword-mcp configure

设置过程会通过隐藏输入方式询问 API 密钥（可在 Magic Portal → Settings → API Keys 中创建），并询问要连接哪个客户端：Claude Desktop、Codex、 Claude Code、Cursor，或手动配置。密钥只会保存到 ~/.magicsword/mcp.json（权限模式为 600）。Portal 默认使用 https://www.magicsword.io，并会替换任何已保存的预览来源。自定义来源需要显式指定 --base-url 选项。

设置过程会在标准的用户级位置注册所选客户端，保留其他服务和设置，并为现有的 客户端配置创建私有备份。对于 JSON 客户端和 Codex，它会更新现有的 magicsword 条目。 Claude Code 要求该名称尚未被占用；重试前，请使用其自身的 MCP 命令移除旧注册。 注册 Codex 和 Claude Code 需要安装各自的 CLI。

要直接选择客户端，或在不提示的情况下使用已保存的密钥：

magicsword-mcp configure --client codex
magicsword-mcp configure --non-interactive --client claude-desktop
magicsword-mcp configure --client cursor --client-config /path/to/mcp.json

启动条目使用绝对路径指定 Node 和已安装的服务，因此桌面应用无需继承终端的 PATH 即可启动它。如果移动 Node 安装位置，或在其他 Node 版本下安装软件包，请重新运行设置。 手动设置会为其他本地 stdio MCP 客户端输出不含凭据的启动条目。不带 --client 运行无人值守设置时，只会写入 MagicSword 文件。

重启所选客户端或开启新会话，即可加载 magicsword 及其 22 个工具。让它调用 whoami，然后调用 list_endpoints 以验证访问权限；仅发现工具并不能验证 API 密钥的作用域。 macOS 上的 Claude Desktop 日志位于 ~/Library/Logs/Claude/mcp*.log。仅限浏览器的客户端需要远程 MCP 传输；此软件包提供本地 stdio 服务。

如果需要按客户端覆盖设置，而不是使用 ~/.magicsword/mcp.json，请在该 MCP 宿主的环境中设置 MAGICSWORD_API_KEY，并可选设置 MAGICSWORD_BASE_URL。请勿将 API 密钥放入共享配置片段或截图中。

工具

工具	功能说明
whoami	返回组织、密钥 ID 和作用域。排查问题时始终先调用。
list_endpoints	列出端点，可按平台／状态／主机名 glob 筛选。
show_endpoint	获取单个端点的信息，包括 OS、策略、合规性、升级、心跳和 AMSI 详情。
list_agent_releases	列出可用的 Agent 版本和各平台的最新版本。
find_alerts	按严重性／确认状态／起始时间／主机名／MITRE 技术搜索警报。
list_events	按名称、文件名、路径、哈希、发布者、计算机或程序包系列搜索 Investigate 事件，并可按类型／状态／策略／端点／时间筛选。
triage_alert	直接获取单个警报及其触发事件、元数据和文件上下文；也可选择确认或忽略该警报。
list_policies	列出策略及其当前版本和模式。
show_policy	按 ID 显示单个策略。
manage_policy_rules	列出规则，或按 ID 或名称向策略添加显式规则／从事件派生的规则。对于 Windows WDAC，避免使用显式的扁平哈希规则。
apply_policy_to_endpoints	解析端点并预览策略分配；审批后设置 confirm=true 即可应用。
flip_to_enforcing	通过服务器签发的一次性确认令牌，分两步预览／确认切换。此操作对安全至关重要。
list_intel_sources	发现已启用的全局和组织自有情报源及其 ID，并可按平台和分页筛选。
list_customer_intel_feeds	列出私有情报源或源项目。
manage_customer_intel_feed	创建或更新情报源；删除需要先预览，然后设置 confirm=true。
manage_customer_intel_item	编辑情报源项目；删除需要先预览，然后设置 confirm=true。
upsert_customer_intel_items	将从报告中提取的指标添加到私有情报源。
manage_policy_intel_sources	列出、关联或取消关联策略上的情报源。
upgrade_endpoints	预览所选端点的升级；审批后设置 confirm=true 即可将其加入队列。
request_endpoint_checkin	将端点签到命令加入队列。
mint_enrollment_token	生成一次性 Agent 注册令牌。
agent_install_instructions	返回适用于 macOS／Linux／Windows 的单行安装命令。不调用 API。
写入工具需要在 Magic Portal 中配置相应的 Customer API 作用域，例如
alerts:write、policies:write、endpoints:write 或 intel:write。
事件审查使用 alerts:read；将选定事件转换为策略规则
需要 policies:write。

工具会发布标准 MCP 安全注解。只读发现工具会标记为只读且幂等；强制执行、删除、策略分配、 规则变更和 Agent 升级会标记为破坏性操作，以便 MCP 客户端采用适当的确认交互。

添加和列出策略规则

manage_policy_rules 每次添加只接受一种输入来源：用于显式 规则的 rules，或用于从遥测数据派生规则的 event_ids。每种来源接受 1–100 个项目。 使用 policy_id，或使用 policy_name 并可选提供 platform 来解析名称。 策略必须已存在；名称有歧义时，需要提供 ID 或平台。

例如，要在 Windows 黑名单策略中阻止问题 #5 中的文件名：

{
  "action": "add",
  "policy_name": "Workstations",
  "platform": "windows",
  "rules": [
    { "type": "filename", "value": "rustdesk.exe", "status": "blocked" },
    { "type": "filename", "value": "mshta.exe", "status": "blocked" },
    { "type": "filename", "value": "wscript.exe", "status": "blocked" }
  ]
}

显式规则使用 type 和 value，并可选提供 status（默认为 blocked）。未知规则字段会被拒绝；rule_type / file_name 不能替代这些字段。文件名和路径值必须是非空字符串或受支持的值对象。发布者值需要 publisherName（或 publisher）以及有效的 tbsHash（或 tbs_hash / certificate_thumbprint）。可选规则元数据包括 name、mode、版本范围、签名者/文件属性引用、 package_version 和 target_platforms。Portal 会验证规则是否可在解析后的策略平台上强制执行。扁平 Windows WDAC 哈希仍不受支持；请使用遥测派生规则或私有情报源。

对于遥测数据，请使用 event_ids，并在顶层设置 status（默认为 allowed），还可选设置 type 覆盖值。顶层的 status 和 type 不能与显式 rules 一起使用；请改为在每条规则上设置这些字段。

添加规则会保留现有规则和情报源链接。状态不同的匹配客户规则会被更新；状态已符合请求的规则会作为未更改的重复项报告。信息源拥有的规则会保留其来源信息；与信息源规则不兼容的冲突会返回 API 错误。该工具会报告 Portal 返回的实际 added_count、updated_count 和 duplicate_count，并在结构化输出中保留版本信息。未更改的重复项批次会报告“无需更改”。无法解释的零更改或格式错误的响应均视为错误：重试前请检查当前规则/版本，因为请求可能已创建新版本。写入操作绝不会自动重试。 对于事件派生批次，如果计数总和小于请求的唯一事件数，也会报错：部分事件可能未生成规则。成功变更和版本详情仍会保留在结构化输出中。

若要验证当前版本中存储的规则：

{ "action": "list", "policy_id": "<policy UUID>", "limit": 500, "offset": 0 }

列出规则需要 ID 和 policies:read。它会返回当前版本的已存储客户规则和已物化的信息源规则，并包含 total、limit 和 offset。默认分页大小为 100，最大为 500；请递增 offset，直到读取完所有 total 行。空页面并不表示其他版本，也不表示尚未物化到此版本中的指标。

示例对话

User:   Show me unack'd critical alerts from the last 24h.
Claude: [calls find_alerts severity=critical acknowledged=false since=...]
        → 3 critical alerts on 2 endpoints. Want me to triage the top one?

User:   Yes.
Claude: [calls triage_alert]
        → Evidence chain: cmd.exe spawned by winword.exe with -enc base64.
          MITRE T1059.001. Acknowledge with comment "office macro chain — under investigation"?

User:   Yes, and extract the IOCs from this report into our SOC feed.
Claude: [calls upsert_customer_intel_items]
        → Upserted 47 indicators into feed 8d6...

User:   Show me audited or blocked events from the last day.
Claude: [calls list_events hours=24 status=audited,blocked]
        → 31 events. Here are the file paths, publishers, and hashes.

User:   Allow the first 5 on the Workstations policy.
Claude: [calls manage_policy_rules action=add policy_name=Workstations event_ids=[...] status=allowed]
        → Created a new policy version with 5 allowed rules.

调查事件并关联情报

询问“显示上周 image.png 的已审核文件名事件。”Agent 会调用 list_events，并传入 type=filename、status=audited、file_name=image.png 和 hours=168。file_name 必须完全匹配，区分大小写，且包括标点符号。若要进行更广泛的发现，q 会搜索与 Portal「调查」相同的 7 个字段：名称、文件名、路径、哈希、发布者、计算机和软件包系列。它会执行区分大小写的字面子字符串搜索，最多接受 120 个字符，包括 Unicode 字符、引号、逗号、括号和 Windows 反斜杠。%、_ 和 * 都是字面字符；不支持通配符和字段查询语法。控制字符会被拒绝。查询为空时不应用文本筛选条件。 筛选条件会组合使用，因此 type=filename 会筛选文件名事件，而不是筛选所有碰巧包含文件名的事件类型。省略 type 可跨事件类型搜索。

例如，“查找发布者为 Contoso, Inc. (R&D) 的事件”会使用 list_events q="Contoso, Inc. (R&D)"。若要阻止这些结果中的某个文件，请检查返回的 ID 和规则上下文，选择所需的规则类型，然后调用 manage_policy_rules action=add policy_id=... event_ids=["<selected-event-id>"] status=blocked type=filename。搜索不会更改策略，也不会自动阻止所有匹配项。搜索某个发布者并不意味着要阻止该发布者；实际阻止的对象由所选规则类型决定。在适当情况下，事件 ID 也可用于创建其他受支持的规则，但须通过 Portal 平台验证。

默认时间范围为 24 小时，状态为 audited,blocked；使用 since 指定明确的起始时间。时间范围使用最后观测时间，若没有则回退到创建时间。结果包含文件路径、发布者、哈希、计算机、出现次数、规则上下文和分页信息。使用 limit 和 offset 获取后续页面。这些是规范化后的事件数据，而非原始事件日志。

对于“将 LOLDrivers 情报关联到我的 Windows 策略”，工作流如下：

1. list_policies platform=windows 用于查找策略名称和 ID。
2. list_intel_sources platform=windows 返回可用来源的名称和 ID。 默认只返回已启用的来源；使用 is_enabled=false 可查看已禁用的来源。 使用 limit（最多 100）和 offset 查找后续页面。
3. manage_policy_intel_sources action=list policy_id=... 显示当前关联项。
4. 确认目标策略和来源后，使用 manage_policy_intel_sources action=attach policy_id=... source_ids=[...]。 结果会分别报告新关联项和已关联的来源。
5. 再次列出策略关联项，以验证结果。

发现来源需要 intel:read，发现策略和列出关联项需要 policies:read，关联来源需要 policies:write。可见来源并不保证拥有高级功能授权；API 会在关联时检查授权。关联会创建一个策略版本，并在终端接收该版本后生效。

配置来源，按优先级排序

1. MAGICSWORD_API_KEY / MAGICSWORD_BASE_URL 环境变量（由 MCP 宿主设置）。
2. ~/.magicsword/mcp.json（或 $MAGICSWORD_CONFIG）。
3. 默认基础 URL https://www.magicsword.io。

可选传输控制项包括 MAGICSWORD_REQUEST_TIMEOUT_MS（默认 30 秒）、MAGICSWORD_RESPONSE_MAX_BYTES（默认 4 MiB）和 MAGICSWORD_GET_RETRIES（默认 2，最多 3 次）。仅重试幂等的 GET 请求；写入操作绝不会自动重试。

安全说明

• flip_to_enforcing 分两步执行。 首次调用会返回服务器预览和一次性确认令牌；你必须向人工审核者展示预览，并传回令牌以完成提交。令牌有效期短，且只能使用一次。这不属于 MFA，也不是由服务器验证的人工审批：同一个 API 密钥即可执行这两次调用。MCP 主机必须在提交前获得人工批准。提交响应必须确认所请求的策略已成功变更，并指出其新版本；否则，请使用 show_policy 验证结果后再重试。成功响应确认服务器策略版本已变更。端点策略会在设备签入后生效；此响应不确认策略已下发到端点。
• Intel 附件使用已启用的数据源，每批最多 60 个。 捕获请求与 Portal UI 共用 API 密钥创建者的速率配额。429 响应会提供重试指引；请等待后再提交下一批。附件摘要会分别报告新附加和已附加的数量。若数量无效或不完整，重试前必须先列出附件。
• 舰队变更和删除均需明确确认。 端点升级、策略分配和私有情报删除都会返回无操作预览，除非后续的已批准调用包含 confirm=true。
• 编辑 Windows WDAC 策略时不应使用明确的平面文件哈希。 批准审核事件时，请使用 manage_policy_rules 搭配 event_ids，以便 Portal 派生受支持的路径 / 发布者 / 文件名规则；或者在私有数据源中使用 upsert_customer_intel_items 添加哈希、AuthentiHash、页哈希和 TBS 情报。
• 机密信息应保留在用户的计算机上。 MCP 服务是本地 stdio 进程；API 密钥从 ~/.magicsword/mcp.json（模式 600）或 MCP 主机传入的环境变量中读取。除发送到已配置的 MAGICSWORD_BASE_URL 的请求外，不会有任何信息离开本机。
• 远程 Portal URL 必须使用 HTTPS。 仅在本地开发时接受普通 HTTP。配置的 URL 不得包含凭据、路径、查询字符串或片段。

开发

npm install
npm run build
npm test
npm run test:package
npm run release:verify
node dist/index.js --version

测试会验证 --help、--version、生产环境默认迁移、私有客户端注册、保留和回滚、配置验证、密钥脱敏、新旧 MCP 启动方式、聚焦变更确认、重试和超时语义、响应大小限制、格式错误的响应、写入操作不重试行为、全部 22 个工具通过新旧 stdio 的 HTTP 契约和确认流程、显式文件名往返、无效规则结构、含糊输入、实际变更数量以及 npm 打包内容。test:package 会安装仅包含生产依赖的 tarball，并检查已安装的 CLI 和 MCP 工具发现；release:verify 会检查所有发布元数据。有关 npm 和 MCP Registry 发布，请参阅 docs/RELEASING.md。

运行 npm run build 后，还可以选择运行实时策略测试：

MAGICSWORD_LIVE_TEST=1 MAGICSWORD_TEST_POLICY_ID="<disposable-policy-uuid>" node scripts/live-policy-rules.mjs

请使用已保存的私有凭据或 MAGICSWORD_API_KEY；不要将密钥写入命令或共享日志。此测试会写入策略版本，并要求准备一个可丢弃、尚未分配的 Windows 审计策略，其名称以 MCP issue 5 disposable verification 为前缀，包含超过 1,000 条基线规则，至少附加一个情报来源，并且不存在 rustdesk.exe、mshta.exe 或 wscript.exe 客户规则。 测试会验证追加行为、分页、情报来源保留、重复添加、状态更新、无效输入，以及在存在适用遥测数据时根据事件生成文件名。测试还会通过 stdio 执行发现和读取工具。测试只会打印断言名称和数量。检查后，请删除此可丢弃策略及其版本；测试不会创建或删除该测试夹具。 设置 MAGICSWORD_TEST_PROTOCOL=legacy 可测试旧版实时传输方式。

使用相同的可丢弃策略和选择加入的环境变量，运行 node scripts/live-demo-tools.mjs，即可检查分配、升级和强制执行预览，全部三个平台的安装程序说明，以及一个已禁用临时 feed 的创建、更新、upsert、列表、删除条目、附加、分离和删除 feed 流程。feed 会在 finally 中移除；策略测试夹具仍需手动清理。这些检查绝不会提交端点分配、升级或强制执行操作。实际端点命令、注册令牌以及警报确认/关闭操作均由本地 HTTP 测试夹具覆盖。