MCP Kanka
用于Kanka API集成的MCP（模型上下文协议）服务器。该服务器为AI助手提供了与Kanka活动交互的工具，支持对各种实体类型（如角色、位置、组织等）进行CRUD操作。
此套餐专为满足以下需求而设计 泰格里姆 但可能对使用Kanka和MCP的其他人有用。
特性
- 实体管理：创建、读取、更新和删除Kanka实体
- 搜索和筛选：按名称搜索部分匹配的实体，按类型/标签/日期过滤
- 批量操作：在单个请求中处理多个实体
- 岗位管理：创建、更新和删除实体上的帖子（注释）
- Markdown支持：Markdown和HTML之间的自动转换，并保留实体提及
- 类型安全：完整的类型提示和验证
- 客户端过滤：超过API限制的增强过滤
- 同步支持：通过时间戳跟踪和Kanka的原生lastSync功能实现高效同步
- 时间戳跟踪：所有实体都包括created_at和updated_at时间戳
需求
- Python 3.10或更高版本（推荐3.13.5）
- Kanka API代币和活动ID
安装
来自PyPI
pip install mcp-kanka来源（使用紫外线）
git clone https://github.com/ervwalter/mcp-kanka.git
cd mcp-kanka
uv sync --all-groups
uv pip install -e .来源（使用pip）
git clone https://github.com/ervwalter/mcp-kanka.git
cd mcp-kanka
pip install -e .快速开始
添加到Claude桌面
- 设置环境变量：
- KANKA_TOKEN：您的Kanka API代币 - KANKA_CAMPAIGN_ID：您的活动ID
- 添加到Claude桌面配置：
{
"mcpServers": {
"kanka": {
"command": "python",
"args": ["-m", "mcp_kanka"],
"env": {
"KANKA_TOKEN": "your-token",
"KANKA_CAMPAIGN_ID": "your-campaign-id"
}
}
}
}与Claude Code CLI一起使用
claude mcp add kanka \
-e KANKA_TOKEN="your-token" \
-e KANKA_CAMPAIGN_ID="your-campaign-id" \
-- python -m mcp_kanka支持的实体类型
- 角色 -玩家角色（PC）、非玩家角色（NPC）
- 生物 -怪物类型、动物、非独特生物
- 位置 -地点、地区、建筑、地标
- 组织 -行会、政府、邪教、公司
- 种族 -物种、祖先
- 备注 -内部内容、会议摘要、总经理笔记（默认为私人）
- 期刊 -会议总结、叙述、编年史
- 任务 -任务、目标、故事情节
可用工具（共9个）
实体运营
find_entities
使用全面的选项搜索和过滤实体，并同步元数据。
参数：
entity_type（可选）：按角色、生物、地点、组织、种族、笔记、日记、任务类型进行筛选query（可选）：用于跨名称和内容进行全文搜索的搜索词name（可选）：按名称筛选（默认情况下部分匹配，例如“Test”匹配“Test Character”）name_exact（可选）：使用精确名称匹配而不是部分名称匹配（默认值：false）name_fuzzy（可选）：启用拼写公差模糊匹配（默认值：false）type（可选）：按用户定义的类型字段过滤（例如，“NPC”、“City”）tags（可选）：标签数组-返回具有所有指定标签的实体date_range（可选）：仅适用于日记账-按日期范围筛选start和end日期limit（可选）：每页结果（默认值：25，最大值：100，全部使用0）page（可选）：分页页码（默认值：1）include_full（可选）：包括完整的实体详细信息（默认值：true）last_synced（可选）：ISO 8601时间戳，仅获取在此时间之后修改的实体
退货：
{
"entities": [...],
"sync_info": {
"request_timestamp": "2024-01-01T12:00:00Z",
"newest_updated_at": "2024-01-01T11:30:00Z",
"total_count": 150,
"returned_count": 25
}
}create_entities
使用markdown内容创建一个或多个实体。
参数：
entities：要创建的实体数组，每个实体具有：
- entity_type （必填）：要创建的实体类型 - name （必填）：实体名称 - entry （可选）：Markdown格式的描述 - type （可选）：用户定义的类型字段（例如“NPC”、“玩家角色”） - tags （可选）：标记名数组 - is_hidden （可选）：如果为真，则对玩家隐藏（仅限管理员）
退货： 创建的实体及其ID和时间戳的数组
update_entities
更新一个或多个现有实体。
参数：
updates：更新数组，每个更新包含：
- entity_id （必填）：要更新的实体ID - name （必需）：实体名称（Kanka API要求，即使不变） - entry （可选）：以Markdown格式更新内容 - type （可选）：更新类型字段 - tags （可选）：更新了标签数组 - is_hidden （可选）：如果为真，则对玩家隐藏（仅限管理员）
退货： 每次更新的成功/错误状态的结果数组
get_entities
使用可选帖子按ID检索特定实体。
参数：
entity_ids（必需）：要检索的实体ID数组include_posts（可选）：包括每个实体的帖子（默认值：false）
退货： 包含时间戳和可选帖子的完整实体详细信息数组
delete_entities
删除一个或多个实体。
参数：
entity_ids（必需）：要删除的实体ID数组
退货： 每次删除的成功/错误状态的结果数组
check_entity_updates
高效地检查自上次同步以来哪些实体已被修改。
参数：
entity_ids（必填）：要检查的实体ID数组last_synced（必填）：ISO 8601时间戳，用于检查自
退货：
{
"modified_entity_ids": [101, 103],
"deleted_entity_ids": [102],
"check_timestamp": "2024-01-01T12:00:00Z"
}岗位操作
create_posts
向实体添加帖子（注释）。
参数：
posts：要创建的帖子数组，每个帖子都有：
- entity_id （必填）：需附上职位的实体 - name （必填）：职位名称 - entry （可选）：以Markdown格式发布内容 - is_hidden （可选）：如果为真，则对玩家隐藏（仅限管理员）
退货： 创建的帖子及其ID的数组
update_posts
修改现有帖子。
参数：
updates：更新数组，每个更新包含：
- entity_id （必填）：实体ID - post_id （必填）：要更新的帖子ID - name （必需）：职称（API要求，即使没有变化） - entry （可选）：以Markdown格式更新内容 - is_hidden （可选）：如果为真，则对玩家隐藏（仅限管理员）
退货： 每次更新的成功/错误状态的结果数组
delete_posts
从实体中删除帖子。
参数：
deletions：删除数组，每个都有：
- entity_id （必填）：实体ID - post_id （必填）：要删除的帖子ID
退货： 每次删除的成功/错误状态的结果数组
搜索和筛选
MCP服务器提供增强的搜索功能：
- 内容搜索：实体名称和内容的全文搜索（客户端）
- 名称筛选器：精确或模糊的名称匹配
- 型过滤器：按用户定义的类型字段筛选（例如“NPC”、“City”）
- 标签过滤器：按标签筛选（AND逻辑-实体必须具有所有指定的标签）
- 日期范围：按日期筛选日记账
- 模糊匹配：可选模糊名称匹配，可实现更灵活的搜索
- 上次同步筛选器：使用Kanka的原生lastSync参数仅获取已修改的实体
注意：内容搜索会获取所有实体并在客户端进行搜索，这对于大型广告系列可能较慢，但提供了全面的搜索功能。
同步功能
时间戳支持
所有实体包括 created_at 和 updated_at ISO 8601格式的时间戳，启用：
- 跟踪实体创建或上次修改的时间
- 实施冲突解决策略
- 建立审计跟踪
同步元数据
这 find_entities 工具返回同步元数据，包括：
request_timestamp：提出请求时newest_updated_at：来自返回实体的最新更新\_ attotal_count：匹配实体总数returned_count：此响应中返回的数字
与lastSync高效同步
使用 last_synced 参数，仅获取特定时间后修改的实体：
# Example: Get entities modified in the last 24 hours
result = await find_entities(
entity_type="character",
last_synced="2024-01-01T00:00:00Z"
)批量更新检查
这 check_entity_updates 该工具有效地检查哪些实体已被修改：
# Check which of these entities have changed
result = await check_entity_updates(
entity_ids=[101, 102, 103],
last_synced="2024-01-01T00:00:00Z"
)
# Returns: modified_entity_ids, deleted_entity_ids, check_timestamp发展
设置
# Clone the repository
git clone https://github.com/ervwalter/mcp-kanka.git
cd mcp-kanka
# Install development dependencies
make install运行测试
# Run all tests
make test
# Run with coverage
make coverage
# Run all checks (lint + typecheck + test)
make check代码质量
# Format code
make format
# Run linting
make lint
# Run type checking
make typecheck程序化使用
除了作为MCP服务器外，此包还提供了一个可以直接在Python脚本中使用的操作层：
from mcp_kanka.operations import create_operations
# Create operations instance
ops = create_operations()
# Find entities
result = await ops.find_entities(
entity_type="character",
name="Moradin"
)
# Create an entity
results = await ops.create_entities([{
"entity_type": "character",
"name": "New Character",
"type": "NPC",
"entry": "A mysterious figure"
}])这使得构建同步脚本、批量操作或其他与Kanka交互的工具变得容易。
配置
MCP服务器需要：
KANKA_TOKEN：您的Kanka API代币KANKA_CAMPAIGN_ID：您的Kanka活动ID
资源
服务器提供 kanka://context 解释Kanka的结构和能力的资源。
版本历史记录
v0.1.0
- 初始版本
- Kanka实体的完整CRUD操作
- 批量操作支持
- Markdown/HTML转换，保留实体提及
- 同步支持时间戳跟踪
- 全面的搜索和过滤功能
许可证
麻省理工学院