Local Campaign MCP Obsidian

RPG战役MCP服务器

一种模型上下文协议（MCP）服务器，用于管理存储在黑曜石兼容标记文件中的RPG活动数据（位置和角色）。

特性

• 列出地点：获取所有可用活动地点的列表
• 获取位置详细信息：检索特定位置的详细信息
• 列出字符：获取按派系/组织组织的所有角色列表
• 获取角色详细信息：检索特定角色的详细信息
• 获取到目前为止的故事：从以前的会话中检索会话笔记和活动进度

安装

1. 克隆此存储库
2. 使用uv安装依赖项：

uv sync

配置

设置您的目录

服务器需要设置三个环境变量：

• LOCATIONS_PATH：包含您的位置标记文件的目录
• CHARACTERS_PATH：包含按派系/组织组织的角色标记文件的目录
• SESSIONS_PATH：包含会话笔记的目录

export LOCATIONS_PATH=/path/to/your/campaign/Locations
export CHARACTERS_PATH=/path/to/your/campaign/Characters
export SESSIONS_PATH=/path/to/your/campaign/sessions

例如，如果您使用黑曜石，并在 /Users/you/Documents/Campaign:

export LOCATIONS_PATH=/Users/you/Documents/Campaign/Locations
export CHARACTERS_PATH=/Users/you/Documents/Campaign/Characters
export SESSIONS_PATH=/Users/you/Documents/Campaign/sessions

用法

运行服务器

服务器使用stdio与MCP客户端通信。您必须设置所有环境变量：

LOCATIONS_PATH=/path/to/your/locations CHARACTERS_PATH=/path/to/your/characters SESSIONS_PATH=/path/to/your/sessions python main.py

添加位置

只需将markdown文件添加到您配置的位置目录即可。每个标记文件代表您的广告系列中的一个位置。

示例结构：

/your/campaign/Locations/
├── Tavern.md
├── Forest.md
└── Castle.md

文件名（无 .md 扩展名）将成为您用于检索它的位置名称。

添加字符

角色应按派系/组织组织在子目录中组织。以开头的文件 __ （比如 __table.md)自动忽略。

示例结构：

/your/campaign/Characters/
├── anarchs/
│   ├── __table.md          # Ignored
│   └── Rico "Roadhouse" Vega.md
├── camarilla/
│   ├── __table.md          # Ignored
│   ├── Prince Sebastian Veyron.md
│   └── Adrian Rook.md
└── Mortals/
    ├── Victor Manelli.md
    └── second inquisition/
        ├── Raphael Kirby.md
        └── Sister Clara Ibarra.md

子目录结构决定了角色的组织和文件名（没有 .md 扩展名）成为字符名称。

添加会话备注

会话笔记应存储在 __result 您的会话目录中的文件。此文件包含迄今为止前几次会议的故事。

示例结构：

/your/campaign/sessions/
└── __result

这 __result 该文件应包含关于前几场比赛中发生的事情的markdown格式的笔记。

可用工具

list_location

列出配置目录中的所有可用活动位置。

{
  "name": "list_locations"
}

get_location

按名称检索特定位置的详细信息。

{
  "name": "get_location",
  "arguments": {
    "name": "Tavern"
  }
}

list_字符

列出按组织/派系分组的所有可用角色。

{
  "name": "list_characters"
}

get_character

按名称和组织检索特定字符的详细信息。

{
  "name": "get_character",
  "arguments": {
    "name": "Prince Sebastian Veyron",
    "organization": "camarilla"
  }
}

对于嵌套组织，请使用路径格式：

{
  "name": "get_character",
  "arguments": {
    "name": "Raphael Kirby",
    "organization": "Mortals/second inquisition"
  }
}

get_story_so_far

从之前的会话笔记中检索到目前为止的故事。

{
  "name": "get_story_so_far"
}

MCP客户端配置

服务器支持两种传输模式：

本地：克劳德桌面（stdio）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "rpg-campaign": {
      "command": "python",
      "args": ["/absolute/path/to/local-campaign-mcp-obsidian/main.py"],
      "env": {
        "LOCATIONS_PATH": "/absolute/path/to/your/campaign/Locations",
        "CHARACTERS_PATH": "/absolute/path/to/your/campaign/Characters",
        "SESSIONS_PATH": "/absolute/path/to/your/campaign/sessions"
      }
    }
  }
}

或者，如果使用紫外线：

{
  "mcpServers": {
    "rpg-campaign": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/local-campaign-mcp-obsidian/main.py"],
      "env": {
        "LOCATIONS_PATH": "/absolute/path/to/your/campaign/Locations",
        "CHARACTERS_PATH": "/absolute/path/to/your/campaign/Characters",
        "SESSIONS_PATH": "/absolute/path/to/your/campaign/sessions"
      }
    }
  }
}

重要：在配置文件中使用绝对路径，而不是相对路径。

______________________________________________________________________

远程部署（HTTP模式）

您可以在任何机器上托管服务器，并通过网络从Claude连接到它。

1.生成API密钥

服务器需要至少32个字符的密钥。生成一个：

python3 -c "import secrets; print(secrets.token_hex(32))"

保持这个值——在下面的每个Claude客户端配置中都需要它。

2.启动服务器

export LOCATIONS_PATH=/path/to/campaign/Locations
export CHARACTERS_PATH=/path/to/campaign/Characters
export SESSIONS_PATH=/path/to/campaign/sessions
export MCP_TRANSPORT=http
export MCP_API_KEY=
export MCP_PORT=8000        # optional, default 8000
export MCP_HOST=0.0.0.0     # optional, default 0.0.0.0

python main.py
# or: uv run python main.py

服务器监听 http://: /mcp.\ 将其置于TLS终止反向代理（nginx、Caddy等）之后，以供生产使用。

3.连接克劳德

克劳德代码（CLI）

claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  rpg-campaign \
  http://your-server:8000/mcp

Claude.ai（网络）

限制：web UI连接器表单仅支持OAuth，它没有用于 静态承载令牌。以下步骤使用 API克劳德 相反，它确实接受 直接使用不记名代币。如果你想让连接器UI工作，你需要添加 服务器支持OAuth。

通过克劳德API （与此服务器使用的Bearer令牌一起使用）：

import anthropic

client = anthropic.Anthropic(api_key="YOUR_ANTHROPIC_API_KEY")
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=1000,
    messages=[{"role": "user", "content": "List all campaign locations."}],
    mcp_servers=[{
        "type": "url",
        "url": "https://your-server:8000/mcp",
        "name": "rpg-campaign",
        "authorization_token": "your-mcp-api-key",
    }],
    betas=["mcp-client-2025-11-20"],
)
print(response.content)

通过连接器UI （作为参考，需要服务器上的OAuth）：

1. 首选 https://claude.ai/settings/connectors
2. 点击 添加自定义连接器
3. 输入服务器URL: https://your-server:8000/mcp
4. 在...之下 高级设置，填写OAuth 客户端ID 和 客户端密钥
5. 点击 添加

您的服务器必须可以通过以下方式公开访问 超文本传输安全协议 （不是纯HTTP）。

克劳德桌面（通过 mcp-remote 代理）

Claude Desktop本机不支持远程HTTP服务器。请先安装代理：

npm install -g mcp-remote

然后添加到 claude_desktop_config.json\ （macOS： ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rpg-campaign": {
      "command": "npx",
      "args": [
        "mcp-remote@latest",
        "http://your-server:8000/mcp",
        "--header",
        "Authorization:Bearer ${MCP_API_KEY}"
      ],
      "env": {
        "MCP_API_KEY": "your-api-key-here"
      }
    }
  }
}

API（程序）

import anthropic

client = anthropic.Anthropic()
response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=1000,
    messages=[{"role": "user", "content": "List all campaign locations."}],
    mcp_servers=[{
        "type": "url",
        "url": "http://your-server:8000/mcp",
        "name": "rpg-campaign",
        "authorization_token": "your-api-key-here",
    }],
    betas=["mcp-client-2025-11-20"],
)

安全注意事项

• 传输层安全：用反向代理包裹服务器，在公开之前终止HTTPS。API密钥通过HTTP以纯文本形式发送。
• 速率限制：服务器允许每个IP每分钟60个请求。调整 _RateLimiter 在 main.py 如果需要的话。
• API密钥长度：强制的最小长度为32个字符。使用 secrets.token_hex(32) （64个十六进制字符）或更长。

______________________________________________________________________

发展

运行测试

uv run pytest

类型检查

uv run mypy main.py

代码检查

uv run ruff check .

许可证

麻省理工学院