Tattty MCP

可流式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流排放：

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

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

配置服务器

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

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

内置工具

通过传递以下命令调用任何工具 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... 1. Prompt enhanced 1. Generating image with Stability AI... 1. Image generated 1. Uploading to Mixedbread... 1. Complete

• 其他工具至少会发出 Running 和 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/ 公开端点； /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 每次工具调用的标题。
• 使用 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 如果匿名模式被禁用）。连接时，服务器发出 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"

部署说明

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

下一个想法

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