xaffinity MCP

xaffinity MCP 服务

一个用于 Affinity CRM 的 MCP（Model Context Protocol）服务，基于 MCP Bash Framework 构建。

功能

• 实体管理 — 搜索和查找个人、公司及商机
• 工作流管理 — 查看和更新管道状态，管理列表条目
• 关系洞察 — 获取关系强度评分，并查找可建立温暖引荐的路径
• 互动记录 — 记录通话、会议、电子邮件和消息
• 会话缓存 — 高效缓存，尽可能减少 API 调用

快速开始

# 1. Install the xaffinity CLI
pipx install "affinity-sdk[cli]"

# 2. (Optional) Configure your API key - Claude Desktop will prompt if skipped
xaffinity config setup-key

# 3. Install the MCP server (choose one)
#    - Claude Desktop: Download and double-click xaffinity-mcp-*.mcpb
#    - Other clients: See "Manual Installation" below
#    - Claude Code: /plugin marketplace add yaniv-golan/affinity-sdk

前提条件

用于 Claude Desktop / MCPB 安装（推荐）

.mcpb 程序包是自包含的 — 其中包含 MCP Bash Framework 和 gojq。你只需要：

要求	安装方式	验证
Python 3.10+	python.org 或你的软件包管理器	python --version
xaffinity CLI	pipx install "affinity-sdk[cli]"	xaffinity --version
Affinity API 密钥	xaffinity config setup-key（或由 Claude Desktop 提示输入）	xaffinity config check-key

CLI 和扩展需要保持同步。 两者需要分别安装。升级其中一个时，也要升级另一个：运行 pipx upgrade affinity-sdk 后下载最新版 .mcpb，反之亦然。自 MCP 1.25.2 起，如果 CLI 版本低于扩展所需版本，修改操作会被拒绝（“此 MCP 服务需要 xaffinity CLI … 或更高版本才能进行修改”），而读取操作仍会运行，但会警告结果可能不完整。较旧的扩展搭配较新的 CLI 时，可能会在不说明原因的情况下失败（例如，使用 CLI 1.22.0 进行合并需要扩展 1.25.1 或更高版本）。Claude Desktop 不会更新从 .mcpb 文件安装的扩展：每次发布新版本后，都需要自行安装。

用于手动安装

手动安装需要额外的依赖项：

要求	安装方式	验证
Bash 3.2+	macOS/Linux 自带；Windows：使用 WSL 或 Git Bash	bash --version
Python 3.10+	python.org 或你的软件包管理器	python --version
jq 或 gojq	参见下方的安装 jq/gojq	jq --version 或 gojq --version
xaffinity CLI	pipx install "affinity-sdk[cli]"	xaffinity --version
Affinity API 密钥	xaffinity config setup-key	xaffinity config check-key

安装 jq/gojq

jq 或 gojq 均可使用 — 服务会自动检测可用的工具。

如何选择：

• jq（推荐）— 原版，应用广泛，完整支持正则表达式
• gojq — 纯 Go 实现，也支持 YAML，错误消息更清晰

安装 jq：

平台	命令
macOS	brew install jq
Debian/Ubuntu	sudo apt-get install jq
Fedora	sudo dnf install jq
Arch Linux	sudo pacman -S jq
Windows	winget install jqlang.jq 或 choco install jq

安装 gojq（替代方案）：

平台	命令
macOS	brew install gojq
任意平台（需要 Go）	go install github.com/itchyny/gojq/cmd/gojq@latest
下载二进制文件	GitHub Releases

安装

选项 1：Claude Desktop（一键安装）

.mcpb bundle 完全自包含——其中包含 MCP 框架和 JSON 处理器。

1. 安装 xaffinity CLI：pipx install "affinity-sdk[cli]"
2. （可选） 配置 API 密钥：xaffinity config setup-key
   • 如果跳过此步骤，Claude Desktop 会在安装 MCPB 时提示你输入 API 密钥
3. 从最新版本下载 xaffinity-mcp-*.mcpb
4. 双击该文件，或将它拖入 Claude Desktop

注意： MCPB bundle 目前仅适用于 Claude Desktop。其他客户端需要手动安装。

选项 2：Claude Code

/plugin marketplace add yaniv-golan/affinity-sdk
/plugin install affinity-crm-mcp-unofficial@xaffinity

选项 3：手动安装

适用于其他 MCP 客户端或开发用途。需要额外的先决条件。

1. 从最新版本下载 xaffinity-mcp-plugin.zip
2. 解压并配置 MCP 客户端（见下文的使用方法）
3. MCP Bash Framework 运行时已随附于 .mcp-bash/ 中——运行服务无需单独安装。
4. 可选——验证配置。validate 和 doctor 是开发工具，需要完整安装 mcp-bash（随附副本仅包含运行时）；如果缺少该安装，命令会输出固定版本的安装命令：

   ./xaffinity-mcp.sh validate
   

故障排除

验证安装

开始调试前，请按顺序验证每一层是否正常工作：

步骤 1：CLI 安装

首先，验证 CLI 已安装并能访问 Affinity API。请参阅 CLI：验证安装。

# Check CLI is installed
xaffinity --version

# Check API connectivity (set your API key - same one entered in Claude Desktop)
AFFINITY_API_KEY="your-key-here" xaffinity whoami --json

如果 whoami 一直无响应，请检查网络连接（防火墙、代理、VPN）。

步骤 2：MCP 服务

CLI 正常工作后，端到端测试 MCP 服务。

首先，找到 MCP 服务目录：

# MCPB installation (macOS)
cd ~/Library/Application\ Support/Claude/Claude\ Extensions/local.mcpb.yaniv-golan.xaffinity-mcp/server

# Or find it automatically
cd "$(find ~ -name 'xaffinity-mcp.sh' -type f 2>/dev/null | head -1 | xargs dirname)"

其他平台/安装方式

安装方式	路径
MCPB（Windows）	%APPDATA%\Claude\Claude Extensions\local.mcpb.yaniv-golan.xaffinity-mcp\server\
手动安装	你选择的解压位置
开发环境	<repo>/mcp/

对于 MCPB 安装：如果步骤 1 通过，则安装已完成。MCP 服务会调用 CLI，因此只要 CLI 能使用你的 API 密钥，MCP 服务也可以。重启 Claude Desktop 并在那里测试工具。

对于手动安装：你也可以直接测试 MCP 层：

AFFINITY_API_KEY="your-key-here" \
  mcp-bash run-tool execute-read-command \
  --args '{"command":"whoami"}'

预期结果：包含你的用户信息的 JSON 响应。

如果步骤 1 正常而步骤 2 失败，则问题出在 MCP 层。运行诊断（需要完整安装 mcp-bash，而不只是随附运行时——见手动安装的步骤 4）：

./xaffinity-mcp.sh doctor
./xaffinity-mcp.sh validate

常见问题

错误	原因	解决方案
"Could not detect xaffinity CLI"	未安装 CLI	pip install "affinity-sdk[cli]"
"older than this MCP server needs" / "This MCP server needs the xaffinity CLI X or later"	CLI 版本过旧	pipx upgrade affinity-sdk 或 pip install --upgrade "affinity-sdk[cli]"
"API key not configured"	缺少凭据	xaffinity config setup-key
"No JSON processor found"	未安装 jq/gojq（仅适用于手动安装）	请参阅安装 jq/gojq
"Framework not found"	缺少随附的 .mcp-bash/ 目录	cd mcp && mcp-bash vendor
每次调用工具都失败，并提示 "server.d/policy.sh was not loaded"	服务的文件夹、server.d 或 policy.sh 对组用户或其他用户可写（克隆或解压时使用 umask 002 后常会出现此问题），或者它是符号链接，或归其他用户所有。此时，服务会拒绝在没有策略的情况下运行（只读模式和其他限制）。	运行错误提示中列出的 chmod go-w ... 命令（或运行 chmod -R go-w <server folder>），然后重启服务

如需详细调试说明，请参阅 docs/DEBUGGING.md。

用法

使用 Claude Code

该服务可通过 .claude-plugin/mcp.json 中的 Claude 插件自动使用。

使用其他 MCP 客户端

将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "xaffinity": {
      "command": "/path/to/affinity-sdk/mcp/xaffinity-mcp.sh"
    }
  }
}

工具

CLI 网关（主要接口）

CLI 网关以最低的令牌开销，提供对 xaffinity CLI 的完整访问：

工具	说明
discover-commands	按关键词搜索 CLI 命令（例如，“创建人物”“删除备注”）
execute-read-command	执行只读 CLI 命令（获取、搜索、列出）
execute-write-command	执行 CLI 写入命令（创建、更新、删除）

查询工具

工具	说明
query	使用筛选条件、联接和聚合执行结构化 JSON 查询

对于复杂的数据分析（筛选、分组、聚合），请使用 query 工具，而不是单独的 CLI 命令。完整文档请参阅查询语言参考。

实用工具

工具	说明
get-entity-dossier	获取实体的综合信息（汇总 5 次或更多 CLI 调用）
read-xaffinity-resource	读取静态 MCP 资源（如 data-model 等）

CLI 网关用法

1. 发现合适的命令：

   {"query": "add person to list", "category": "write"}
   

   返回紧凑的文本格式：

   # cmd|cat|params (s=str i=int b=bool f=flag !=req *=multi)
   list entry add|w|LIST:s! --person-id:i --company-id:i
   

2. 执行命令：

   {"command": "list entry add", "argv": ["Pipeline", "--person-id", "123"]}
   

输出格式

控制命令结果的格式，以优化令牌效率：

{"command": "person ls", "format": "markdown"}

格式	令牌效率	适用场景
json	低	程序化使用（默认）
markdown	中高	便于大模型理解——最适合分析任务
toon	高（约少 40%）	大型数据集、批量操作
csv	中	电子表格导出
jsonl	中	流式工作流

建议：

• 需要分析或总结数据时使用 markdown（大模型擅长读取表格）
• 导出大量数据时使用 toon，以尽量减少令牌用量（比 JSON 小 30%–60%）
• 需要完整结构并包含分页和元数据时使用 json

破坏性命令

无法撤销的命令（删除、合并）需要用户确认：

• 在支持确认对话框（MCP elicitation）的客户端中，服务会直接询问你。
• Claude Desktop 扩展不会显示对话框。 工具会拒绝首次调用，并告知 Claude 在对话中征求你的同意；只有在你同意后，Claude 才会使用 confirm: true 重试：

{"command": "person delete", "argv": ["456"], "confirm": true}

工具会为 CLI 附加 --yes。从 MCP 1.27.0 开始，confirm: true 只有在服务于最近 15 分钟内拒绝过完全相同的命令（或显示过确认对话框）后才会生效一次：如果 Claude 在首次调用时设置了该参数，调用会被拒绝，并提示 Claude 征求你的同意。服务无法查看对话内容，因此无法判断你是否真的同意：请保持 Claude Desktop 的 execute-write-command 工具审批提示开启，不要选择“始终允许”——这个提示正是需要你确认的检查步骤。

也在使用 Affinity 自带的连接器？ 如果此扩展和 Affinity 的 claude.ai 连接器都已连接，Claude 可能会选择其中任意一个。如果你指的是此连接器，请说“使用 xaffinity 工具”。

提示词

提示词	描述
prepare-briefing	为会议准备全面的背景信息
log-interaction-and-update-workflow	记录互动并更新管道
pipeline-review	审查工作流管道
change-status	更改工作流状态并记录说明
warm-intro	查找人脉引荐途径
log-call	快速记录一次电话通话
log-message	快速记录一条聊天／短信
interaction-brief	获取互动历史摘要

配置

API 密钥

MCP 服务使用 xaffinity CLI，该 CLI 按以下顺序解析 API 密钥（优先级从高到低）：

优先级	来源	描述
1	--api-key-file	CLI 标志（从文件读取，或使用 - 从标准输入读取）
2	--api-key-stdin	CLI 标志（从标准输入读取）
3	AFFINITY_API_KEY 环境变量	← Claude Desktop 会设置此项。使用 --dotenv 加载的 .env 文件也可以设置此项
4	AFFINITY_API_KEY_FILE 环境变量	包含密钥的文件路径
5	AFFINITY_API_KEY_COMMAND 环境变量	输出内容为密钥的命令
6	配置文件	用户配置文件中的 api_key（xaffinity config path）

MCP 服务不会传递密钥标志，因此对于它而言，环境变量优先。

Claude Desktop / MCPB：在 Claude Desktop 配置界面中输入 API 密钥时，该密钥会作为 AFFINITY_API_KEY 环境变量传递给 MCP 服务（优先级 3）。这意味着：

• 它会覆盖 AFFINITY_API_KEY_FILE、AFFINITY_API_KEY_COMMAND 和你的配置文件
• 如果你已通过 xaffinity config setup-key 配置密钥，并且也在 Claude Desktop 中输入了密钥，则以 Claude Desktop 中的密钥为准

建议：只使用以下其中一种方法：

• 仅使用 Claude Desktop：在 MCPB 配置界面中输入密钥（最简单）
• CLI + MCP：运行 xaffinity config setup-key，并将 Claude Desktop 中的密钥栏留空
• 环境变量：在 shell 配置文件中设置 AFFINITY_API_KEY

只读模式

设置 AFFINITY_MCP_READ_ONLY=1（或 true）以阻止所有写入工具。在 Claude Desktop 捆绑包中，此项设置名为 只读模式。

AFFINITY_MCP_READ_ONLY=1 ./xaffinity-mcp.sh

禁用破坏性命令

设置 AFFINITY_MCP_DISABLE_DESTRUCTIVE=1（或 true），允许写入操作，但阻止无法撤销的命令（删除、合并），即使已确认也不例外。在捆绑包中，此项设置名为禁用 破坏性命令。

AFFINITY_MCP_DISABLE_DESTRUCTIVE=1 ./xaffinity-mcp.sh

**检查设置是否生效：**请 Claude 执行一次 dry-run person delete 1。启用只读模式时，命令会被拒绝，并返回“Writes are off: the server is in read-only mode”；禁用破坏性命令时，则会返回 destructive_disabled。无论哪种情况，都不会更改任何内容。

缓存 TTL

调整缓存时长（默认 10 分钟）：

AFFINITY_SESSION_CACHE_TTL=300 ./xaffinity-mcp.sh

Affinity API 版本

默认情况下，每个请求都会使用 API 密钥的默认 Affinity V2 API 版本。若要固定版本 （例如获取最新的响应结构），请设置 AFFINITY_API_VERSION（或在 Claude Desktop 的扩展设置中填写 Affinity API Version）：

AFFINITY_API_VERSION=2026-09-17 ./xaffinity-mcp.sh

可接受的值：2024-01-01、2026-07-15、2026-09-17 或 current（始终使用最新版本）。 AFFINITY_PROFILE 也会被传递，因此可以选择 xaffinity 配置文件中的配置项 （包括其 api_version）。工具结果会在 meta.affinityApiVersion 中报告响应所使用的版本。请参阅 API 版本指南。

更新通知

MCP 服务会在启动时检查 CLI 更新；若有新版本可用，则会显示警告。这有助于仅使用 MCP 的用户（不直接运行 CLI 命令）及时更新。

更新检查：

• 不阻塞：在后台运行检查，不会延迟服务启动
• 有限制：后台检查每 24 小时最多运行一次
• 尊重选择：遵从用户通过 XAFFINITY_NO_UPDATE_CHECK=1 或配置文件进行的退出设置

若要禁用更新通知：

# Via environment variable
XAFFINITY_NO_UPDATE_CHECK=1 ./xaffinity-mcp.sh

# Or via CLI config
xaffinity config update-check --disable

开发

运行诊断

./xaffinity-mcp.sh doctor

调试模式

启用调试日志以排查问题。调试模式会在启动时显示版本信息，并为所有日志消息添加组件前缀。

# Persistent debug mode (recommended - survives reinstalls)
mkdir -p ~/.config/xaffinity-mcp && touch ~/.config/xaffinity-mcp/debug

# Session-only via environment variable
XAFFINITY_MCP_DEBUG=1 ./xaffinity-mcp.sh

# Disable persistent debug mode
rm ~/.config/xaffinity-mcp/debug

启用调试模式后，日志会显示：

[xaffinity-mcp:1.2.3] Debug mode enabled
[xaffinity-mcp:1.2.3] Versions: mcp=1.2.3 cli=0.6.9 mcp-bash=v0.9.3
[xaffinity-mcp:1.2.3] Process: pid=12345 started=2026-01-06T10:30:00-08:00

日志位置

场景	日志位置
Claude Desktop（macOS）	~/Library/Logs/Claude/mcp-server-xaffinity MCP.log
Claude Desktop（Windows）	%APPDATA%\Claude\Logs\mcp-server-xaffinity MCP.log
独立 CLI	stderr（控制台）

高级调试选项

变量	描述
XAFFINITY_MCP_DEBUG=1	启用调试模式（级联到所有组件）
MCPBASH_LOG_VERBOSE=true	在日志中显示路径（会暴露文件路径）
MCPBASH_TRACE_TOOLS=true	为工具启用 Shell 跟踪（set -x）

完整的调试指南请参阅 docs/DEBUGGING.md。

Claude Code 插件

MCP 服务也以 Claude Code 插件的形式提供，通过仓库自带的市场（.claude-plugin/marketplace.json）分发。若要在其他客户端中独立使用 MCP 服务，请参阅主要的 MCP 文档。

发布前必须先组装插件文件：

构建插件

make plugin

这会将 MCP 服务文件复制到 .claude-plugin/ 中：

• xaffinity-mcp.sh、xaffinity-mcp-env.sh
• tools/、prompts/、resources/、lib/
• completions/、providers/、scripts/、server.d/

清理构建产物

make clean

插件结构

.claude-plugin/
├── plugin.json          # Plugin manifest (checked in)
├── skills/              # Claude Code skills (checked in)
├── xaffinity-mcp.sh     # MCP server (copied by make)
├── tools/               # MCP tools (copied by make)
├── prompts/             # MCP prompts (copied by make)
└── ...                  # Other MCP files (copied by make)

发布说明请参阅 CONTRIBUTING.md。

许可证

请参阅主仓库的许可证。