storyworld mcp-FastMCP兼容mcp服务器
轻量级MCP服务器，为代理模拟提供角色上下文和资源。服务器使用FastMCP v3模式（生命周期启动、资源即工具转换和可选的基于文件的动态工具）。
此回购包含什么✅
- FastMCP工具，公开角色上下文和资源下载工具
- 从GitHub获取角色YAML和从Hugging Face获取图像的下载器
- FastMCP v3生命周期启动，用于首次运行资产引导
- 可选的
tools/在开发过程中提供额外工具 - 当地发展的示例人物和图像
- 测试、Dockerfile和GitHub操作CI
快速入门（本地）🔧
- 创建一个venv并安装依赖项：
python -m venv .venv
.\.venv\Scripts\activate # Windows
pip install -r requirements.txt- （可选）创建
.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- 为MCP客户端运行FastMCP服务器（MCP协议）：
# runs FastMCP on port 3334 by default
python -m mcp_server.mcp_app- 可选：为放入的Python工具启用自动重新加载
./tools:
FASTMCP_TOOLS_RELOAD=1 python -m mcp_server.mcp_app --transport http --host 0.0.0.0 --port 3334FastMCP工具（示例）💡
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//index.html+story.jsonlist_stories()--在下面列出故事包STORIES_DIRinit_story_repo(story_id, github_repo?)--初始化故事和可选来源的本地git仓库commit_story_repo(story_id, message?)--同步故事包并提交更改push_story_repo(story_id, github_repo?, branch?)--使用推送到GitHubGITHUB_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=...) 1. build_story_page(story_id=..., character_codes=[...]) 1. init_story_repo(...), commit_story_repo(...), push_story_repo(...) 当他们想要git支持的故事出版时
- 发布
stories//直接访问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 if needed)
gh repo create /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存储库机密。
______________________________________________________________________
我可以为你做的下一步（选择任何一个）：
- 创建公共GitHub仓库并推送初始提交（我可以输出确切的命令）。
- 添加发布就绪
mcp.json并发布到静态宿主端点。 - 将远程角色YAMLs/图像导入仓库（如果你想跟踪它们）。