AI导哈

角色上下文服务器

一个轻量级的MCP服务器，提供角色上下文和资源以支持角色扮演代理。

  • by venetanji
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 venetanji/storyworld-mcp

使用说明

storyworld mcp-FastMCP兼容mcp服务器

轻量级MCP服务器，为代理模拟提供角色上下文和资源。服务器使用FastMCP v3模式（生命周期启动、资源即工具转换和可选的基于文件的动态工具）。

此回购包含什么✅

  • FastMCP工具，公开角色上下文和资源下载工具
  • 从GitHub获取角色YAML和从Hugging Face获取图像的下载器
  • FastMCP v3生命周期启动，用于首次运行资产引导
  • 可选的 tools/ 在开发过程中提供额外工具
  • 当地发展的示例人物和图像
  • 测试、Dockerfile和GitHub操作CI

快速入门（本地）🔧

  1. 创建一个venv并安装依赖项：
python -m venv .venv
.\.venv\Scripts\activate    # Windows
pip install -r requirements.txt
  1. （可选）创建 .env 从示例和调整源代码中：
cp .env.example .env
# edit .env to set HF dataset or GitHub repo overrides

推荐 .env 为您的实验室/本地流程添加：

WORKSPACE_DIR=/path/to/storyworld-workspace
COMFYUI_URL=http://127.0.0.1:8188
COMFY_OUTPUT_DIR=/path/to/storyworld-workspace/comfy-output
STORIES_DIR=/path/to/storyworld-workspace/stories
COMFY_MCP_AUTO_SPAWN=1
FASTMCP_SHOW_BANNER=0
FASTMCP_LOG_LEVEL=WARNING
  1. 为MCP客户端运行FastMCP服务器（MCP协议）：
# runs FastMCP on port 3334 by default
python -m mcp_server.mcp_app
  1. 可选：为放入的Python工具启用自动重新加载 ./tools:
FASTMCP_TOOLS_RELOAD=1 python -m mcp_server.mcp_app --transport http --host 0.0.0.0 --port 3334

FastMCP工具（示例）💡

  • list_characters() --返回可用字符代码
  • get_character_context(code) --返回给定字符的MCP样式上下文有效负载
  • get_character_context_compact(code) --仅返回配置文件+媒体引用（无嵌入式图像二进制）
  • get_character_media_manifest(code) --返回包含文件元数据的本地/公共媒体清单
  • refresh_character(code) --刷新一个字符的YAML和图像资源
  • get_runtime_capabilities() --返回活动运行时dirs/flags(COMFY_OUTPUT_DIR, STORIES_DIR，代理状态）
  • ingest_comfy_outputs(code, story_id?, limit?, mode?) --从本地Comfy输出文件夹中获取最新媒体
  • build_story_page(story_id, title?, character_codes?, notes?) --写入静态 stories/<story_id>/index.html + story.json
  • list_stories() --在下面列出故事包 STORIES_DIR
  • init_story_repo(story_id, github_repo?) --初始化故事和可选来源的本地git仓库
  • commit_story_repo(story_id, message?) --同步故事包并提交更改
  • push_story_repo(story_id, github_repo?, branch?) --使用推送到GitHub GITHUB_TOKEN/GH_TOKEN

客户端可以直接连接到FastMCP端点。

可选提供者组成

  • http 模式（公共实例）：默认情况下禁用舒适代理。
  • 集 COMFY_PROXY_IN_HTTP=1 也可以在中启用舒适的代理 http 模式。
  • stdio 模式（实验室/客户端模式）：舒适代理可以从以下任一来源获得：
    • COMFY_MCP_URL （远程/本地HTTP MCP端点），或
    • COMFY_MCP_STDIO_COMMAND + COMFY_MCP_STDIO_ARGS （生成本地comfyui mcp进程）。
    • 如果两者都没有设置，Storyworld会自动生成comfyui mcp：
      • uvx --from ${COMFY_MCP_SERVER_SPEC} ${COMFY_MCP_SERVER_ENTRYPOINT} --comfy-url ${COMFYUI_URL} --output-folder ${COMFY_OUTPUT_DIR}

实验室友好的本地设置🧪

对于学生实验室的机器，请在本地运行ComfyUI+Comfy MCP，并将此服务器也保持在本地。

  • 集 COMFY_OUTPUT_DIR 到Comfy写入生成文件的文件夹。
  • 集 STORIES_DIR 到静态故事包的可写文件夹中。
  • WORKSPACE_DIR 可以用作包含所有内容的单个根文件夹：
    • characters/ （下载的个人资料+图片）
    • comfy-output/ （生成要摄取的媒体）
    • stories/ （故事包+html输出）
  • 可选故事库配置：
    • STORY_REPOS_DIR 本地repo根目录
    • STORY_GITHUB_REPO 默认 owner/repo 对于推
    • GITHUB_TOKEN 或 GH_TOKEN 用于经过身份验证的GitHub API/推送操作
  • 学生可以调用生成工具（他们当地的Comfy MCP），然后调用：
    1. ingest_comfy_outputs(code=..., story_id=...)
    2. build_story_page(story_id=..., character_codes=[...])
    3. init_story_repo(...), commit_story_repo(...), push_story_repo(...) 当他们想要git支持的故事出版时
  • 发布 stories/<story_id>/ 直接访问GitHub Pages（或复制到故事仓库并提交）。

启动和按需加载⚡

  • 启动预回迁是可选择的(STARTUP_PREFETCH=1).
  • 保持 DISABLE_AUTO_DOWNLOAD=1 强制纯粹的按需行为。
  • 如果本地缺少字符YAML，则在首次请求时从GitHub获取。
  • 字符图像由字符代码根据需要从Hugging Face中提取，使用部分数据集下载模式而不是完整快照。
  • 这可以使MCP快速启动，并避免stdio/http客户端中的早期超时压力。

数据源和覆盖🔁

默认值（用env变量覆盖或 .env):

  • GitHub字符仓库： venetanji/polyu-storyworld （路径： characters/)
  • 拥抱脸部图像数据集： venetanji/polyu-storyworld-characters

要手动获取资产，请执行以下操作：

python -m scripts.fetch_data --github-repo venetanji/polyu-storyworld --github-path characters --hf-dataset venetanji/polyu-storyworld-characters

测试和CI✅

  • 在本地运行测试： pytest -q
  • GitHub Actions在推送/PR上运行测试（请参阅 .github/workflows/ci.yml).

发布到GitHub（命令）🔁

我为一个名为的公共存储库准备了所有东西 storyworld-mcp 默认情况下。要创建远程并从计算机推送（推荐）：

# create repo with gh (replace <owner> if needed)
gh repo create <owner>/storyworld-mcp --public --source=. --remote=origin
# push local main branch
git add .
git commit -m "chore: initialize FastMCP-compatible storyworld-mcp"
git branch -M main
git push -u origin main

如果你愿意，我可以提供确切的 gh/git 您可以使用GitHub用户名的命令或为您推送仓库（我需要配置PAT）。

安全说明⚠️

不要泄露秘密。使用 .env （忽略）和CI的GitHub Actions存储库机密。

我可以为你做的下一步（选择任何一个）：

  1. 创建公共GitHub仓库并推送初始提交（我可以输出确切的命令）。
  2. 添加发布就绪 mcp.json 并发布到静态宿主端点。
  3. 将远程角色YAMLs/图像导入仓库（如果你想跟踪它们）。

相关 MCP