使用说明

可流式MCP HTTP工具包

一个生产就绪的FastAPI应用程序，实现了端到端的模型上下文协议（MCP）HTTP传输。服务器现在通过单一的JSON-RPC 2.0进行通信 /mcp 端点，维护长期会话，通过服务器发送事件（SSE）流式传输进度，支持承载身份验证、每IP速率限制、OpenAPI文档、经过身份验证的管理面板、健康检查（包括特定于铁路的报告）、结构化JSON日志记录，并且可以通过Docker、ngrok或任何容器平台部署。

先决条件

Python 3.12+
PowerShell（Windows）或任何POSIX shell
可选：Docker用于容器部署

快速开始

cd C:\Users\relay\Downloads\TATTTY-MCP
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn mcp.server:app --host 0.0.0.0 --port 8000

Swagger用户界面可在 http://localhost:8000/docs.

MCP协议端点

1.初始化会话

POST /mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26"
  }
}

响应标头包括 Mcp-Session-Id。在每个后续请求中重复使用该值。

2.打开事件流

GET /mcp
Accept: text/event-stream
Mcp-Session-Id: sess_abc123

SSE连接保持打开并传输 notifications/progress、心跳ping和最终工具结果。

3.列出工具

POST /mcp
Headers: Mcp-Session-Id: sess_abc123
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

4.调用工具

POST /mcp
Headers: Mcp-Session-Id: sess_abc123
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "groq_to_stability",
    "arguments": {
      "selections": {"style": "Japanese", "color": "Full Color"},
      "additional_notes": ["Dragon sleeve"],
      "stability": {"model": "sd3.5-large"}
    }
  }
}

POST请求返回 { "status": "processing" } 立即。SSE流排放：

notifications/progress 事件（例如，增强提示、生成图像、上传到Mixedbread）
JSON-RPC的最终结果 content: [{"type": "text", "text": "{...}"}]

会话在一小时不活动后过期（可配置）。如果您收到 session_closed 通知或无效会话错误。

配置服务器

所有可调参数都存在 mcp/config.yaml:

关键字	描述	默认值
`host`	uvicorn接口	`0.0.0.0`
`port`	监听端口	`8000`
`log_level`	Uvicorn测井水位	`info`
`allow_anonymous`	允许未经身份验证的访问	`true`
`secret_key`	需要时 `allow_anonymous=false`	`null`
`rate_limit_per_ip`	每个IP的请求数/分钟（内置限制器）	`30`
`admin_token`	启用 `/admin` 控制台设置时	`null`
`log_directory`	JSON日志文件夹	`logs`
`cors.*`	允许的起源/方法/标头	`*`

还支持环境覆盖（例如。 MCP_PORT=9000, MCP_ADMIN_TOKEN=supersecret, MCP_LOG_DIR=C:\\data\\logs).

内置工具

工具	说明	示例 `arguments` 有效载荷
`echo`	返回您的消息和元数据。	`{"message":"Hi"}`
`resize_image`	调整远程图像的大小并返回base64 PNG/JPEG/WEBP。	`{"image_url":"https://i.imgur.com/xyz.png","width":320,"height":240,"format":"PNG"}`
`text_stats`	统计字符、单词、句子和阅读时间。	`{"text":"Hello world!"}`
`groq_chat`	向Groq的聊天完成API发送提示（需要 `GROQ_API_KEY`).	`{"prompt":"Summarise this server"}`
`ask_tattty_enhance`	使用TaTTTy提示润色工作流程增强第一人称故事（Groq `openai/gpt-oss-120b`).	`{"story":"my raw story"}`
`stability_sd35_generate`	通过SD3.5 Large/Large Turbo生成文本/图像到图像。	`{"prompt":"a neon fox","model":"sd3.5-large"}`
`stability_remove_background`	删除背景，同时保持透明输出。	`{"image":{"url":"https://..."}}`
`stability_replace_background`	异步背景替换+使用可选引用重新点亮。	`{"subject_image":{"url":"https://..."},"background_prompt":"studio backdrop"}`
`stability_upscale_conservative`	保守的升级者，有创造力+及时的指导。	`{"prompt":"hi-res portrait","image":{"url":"https://..."}}`
`stability_control_sketch`	草图控件（从图形派生的结构）。	`{"prompt":"render the sketch","image":{"url":"https://..."}}`
`stability_control_structure`	结构控制（参考图像的布局指导）。	`{"prompt":"evening city","image":{"url":"https://..."}}`
`stability_control_style`	风格指南（从单一参考中应用美学）。	`{"prompt":"vintage poster","image":{"url":"https://..."}}`
`stability_control_style_transfer`	样式转换（init+样式图像，可选提示）。	`{"init_image":{"url":"https://..."},"style_image":{"url":"https://..."}}`
`groq_to_stability`	单次调用，要求Groq提供修改后的提示/上下文，并将其输入SD3.5。	`{"selections":{"style":"Japanese"},"stability":{"model":"sd3.5-large"}}`

通过传递以下命令调用任何工具 arguments 进入 tools/call JSON-RPC请求如前一节所示。

通过在中添加新模块来添加更多工具 mcp/tools/ 并在里面注册 mcp/tools/__init__.py.

HTTP流详细信息

进展和成果仅通过与以下机构开通的SSE连接交付 GET /mcp.
每个JSON-RPC通知都作为单独的SSE数据行到达。期望 notifications/progress, notifications/heartbeat，可选 notifications/session_closed，最后 result 物体。
这 groq_to_stability 默认情况下，工具会发出以下进度里程碑：
1. Enhancing prompt with Groq...
2. Prompt enhanced
3. Generating image with Stability AI...
4. Image generated
5. Uploading to Mixedbread...
6. Complete
其他工具至少会发出 Running <tool> 和 Complete 信息。
错误遵循JSON-RPC 2.0约定(-32700 解析错误， -32600 无效请求， -32601 未找到方法， -32602 无效参数， -32603 内部错误， -32000 上游/服务故障范围）。

稳定性AI工具

出口 STABILITY_API_KEY （铁路秘密， .env等等）。所有支持稳定性的工具默认使用此服务器范围密钥，但也接受可选密钥 stability_api_key 每个请求都有一个字段，这样您以后就可以携带自己的凭据，而无需重新部署。
可选调谐旋钮： STABILITY_API_BASE （对登台有用）， STABILITY_HTTP_TIMEOUT, STABILITY_POLL_INTERVAL，以及 STABILITY_POLL_ATTEMPTS.
每个Stability端点返回结构化JSON images （base64有效载荷+元数据）并且从不公开 /v2beta/results/{id} 作为公共MCP工具。唯一的异步流（替换背景+重新点亮）在内部轮询该端点，并在单个响应中显示就绪映像。
SD3.5代限制 model 到 sd3.5-large 和 sd3.5-large-turbo，与允许的计划相匹配。
接受二进制数据的输入使用 ImageInput 形状单一 {"url": "https://..."} 加可选 filename/content_type 提示。

管理和可观察性

集 MCP_ADMIN_TOKEN （或 admin_token 内部 config.yaml)启用经过身份验证的控制面板 /admin.通过查询字符串提供令牌(/admin?token=...)或 X-Admin-Token 头球仪表板提供：

深度健康运行加上铁路格式的按需快照
运行时设置管理(allow_anonymous、速率限制、共享密钥）
实时指标（正常运行时间、请求计数器、最近的请求日志）
存储在以下位置的结构化JSON日志的尾部 logs/mcp.log （通过以下方式覆盖 MCP_LOG_DIR)

所有仪表板操作都代理到JSON API /admin/api/*，如果需要，您可以直接从外部可观察性工具调用。

健康检查

除了轻量化 /health，服务器附带了两个更丰富的端点：

/health/deep --练习磁盘空间、出站HTTP、Pillow和每个MCP工具诊断。
/health/railway --用主机名、指标和平台数据包装深度检查。此格式符合Railway的部署健康预期（HTTP 200在5分钟的部署窗口内，达到 healthcheck.railway.app 主机名，根据Tavily文档）。

铁路部署应将健康检查指向 /health/railway端点响应迅速，在JSON有效负载中显示故障，并在部署窗口外保持空闲，正如Railway的文档所描述的那样。

通过Docker运行

docker build -t mcp-toolkit .
docker run -p 8000:8000 --env MCP_ALLOW_ANONYMOUS=true mcp-toolkit

将相同的映像部署到Render/Railway/Fly.io或您自己的VPS。暴露 /mcp/<tool> 公开端点； /docs 自动编写API文档。

与ngrok公开分享

ngrok http 8000

将生成的URL转发给合作者（例如。 https://abcd1234.ngrok.io/mcp/echo).

速率限制和认证

一个轻量级的内存限制器将每个IP限制为每分钟30个请求。调整 rate_limit_per_ip （或设置为 null)调整或禁用。
集 allow_anonymous: false 并提供 secret_key 要求 Authorization: Bearer <key> 每次工具调用的标题。
使用 MCP_ADMIN_TOKEN 以保护管理面板及其API。

格罗克API

出口 GROQ_API_KEY （或在Railway/AAzure/Docker环境中设置） /mcp/groq_chat.
可选字段： system_prompt, model, max_tokens, temperature.
该工具返回响应内容和Groq使用元数据。

询问纹身增强剂

/mcp/ask_tattty_enhance 通过存储在以下位置的TaTTTy系统提示发送原始第一人称故事 mcp/prompts/ask_tattty_system.txt 因此，复制更新保持集中。
需要 GROQ_API_KEY 并以Groq模型为目标 openai/gpt-oss-120b 默认情况下（用覆盖 model 如果Groq添加了新的OSS层）。
请求正文： story （必填），可选 guidance （音调、目标受众等），加上标准采样旋钮(temperature, max_tokens, top_p).
响应返回抛光 enhanced_story，以及Groq model + usage 您可以将元数据导入下游工具。
需要逐个令牌的反馈吗？HTTP端点已经流式传输增量，以及 /ws/mcp 如果您更喜欢WebSockets，则镜像相同的事件。

MCP WebSocket流媒体

打开WebSocket /ws/mcp （包括 Authorization: Bearer <secret> 如果匿名模式被禁用）。连接时，服务器发出 hello payload列出了每个工具以及它是否支持流媒体。

使用JSON格式发送工具调用：

{
  "type": "call_tool",
  "call_id": "client-generated-uuid",
  "tool": "ask_tattty_enhance",
  "arguments": { "story": "...", "guidance": "..." }
}

对于流媒体工具，服务器会回复 call_stream 包括增量有效载荷的事件。 ask_tattty_enhance 发射 { "event": "token", "content": "..." } 对于每个Groq delta，然后以 { "event": "completed", "result": { ... } }.决赛 call_completed 相同的消息 call_id 确认成功。
非流媒体工具仍然返回单个 call_result 反映REST响应的帧。

Groq → 稳定链

/mcp/groq_to_stability 将Groq chat+Stability SD3.5捆绑在一个请求中。提供高层 prompt，可选 context 元数据（目标用户、业务约束等），以及 stability_options 覆盖SD3.5参数，如 model, creativity_scale，或 image_reference URLs/base64。
两者都需要 GROQ_API_KEY 和 STABILITY_API_KEY 存在（或使用内联传递 stability_api_key).处理程序格式化Groq的上下文，将生成的文本中继到SD3.5中，并返回原始Groq消息和Stability图像有效载荷。
当前端不应该处理两个单独的API调用时，这是理想的选择。服务器在单个MCP工具调用中执行所有链接、日志记录和错误报告。
集 MIXBREAD_API_KEY + MIXBREAD_STORE_ID 自动将每个渲染存档到Mixedbread存储中。请求体接受可选 mixbread 对象（启用/禁用、覆盖存储ID、提供元数据覆盖等），如果您需要每次调用控制。

混合面包储存

出口 MIXBREAD_API_KEY 和 MIXBREAD_STORE_ID 因此服务器可以将生成的PNG/JPEG上传到 https://api.mixedbread.com/v1/files 并在您选择的存储中使用结构化元数据（提示、选择、种子等）引用它们。
API的高级摄入旋钮(parsing_strategy, chunking_strategy, contextualization, external_id, overwrite，自定义 metadata)可以通过以下方式提供 mixbread 对象在 /mcp/groq_to_stability.
Mixbread上传是最好的努力；如果API密钥/存储ID丢失，MCP工具仍然返回Groq+稳定性结果，并报告存储被跳过。

测试

安装可选的开发依赖项并运行下面的冒烟测试：

pip install httpx  # required for FastAPI TestClient
& .\.venv\Scripts\python.exe -c "from fastapi.testclient import TestClient; from mcp.server import app; client=TestClient(app); assert client.post('/mcp/echo', json={'message':'ping'}).status_code==200"

部署说明

将此仓库提交到GitHub。
将Render/Railway/Fly.io连接到仓库，并使用提供的Dockerfile进行部署。
分享 /docs 为了发现或 /openapi.json 用于程序集成。

下一个想法

直接从工具处理程序中包装CLI实用程序（ffmpeg、pandoc、git）。
将日志发送到托管服务（Papertrail、Logtail）以实现可观察性。