commit

Dockerfile

@@ -0,0 +1,15 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /code
+
+COPY requirements.txt .
+RUN pip install --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,39 @@
----
-title: MCP Sample
-emoji: 👀
-colorFrom: pink
-colorTo: yellow
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## サンプル MCP サーバー (Hugging Face Spaces デプロイ用)
+
+このリポジトリは、Hugging Face Spaces にデプロイできるシンプルな MCP 互換 WebSocket サーバーのサンプルです。`/mcp` エンドポイントへ接続すると、以下の 3 種類のアクションで動作確認ができます。
+
+- `ping` : サーバーが `pong` を返却します。
+- `tools.list` : 利用可能なツール（ここでは `echo`）の一覧を返却します。
+- `tool.call` : `echo` ツールに文字列を渡すと、そのまま返却します。
+
+### 1. ローカルでの動作確認
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows の場合は .venv\Scripts\activate
+pip install -r requirements.txt
+uvicorn app:app --host 0.0.0.0 --port 7860
+```
+
+別ターミナルで以下を実行すると、WebSocket プロトコルのやり取りを確認できます。
+
+```bash
+python client.py --url ws://localhost:7860/mcp
+```
+
+### 2. Hugging Face Spaces へのデプロイ手順
+
+1. Hugging Face で新しい Space を作成し、**Space SDK** として **Docker** を選択します。
+2. このリポジトリのファイルをそのままアップロード（または `git push`）します。
+3. ビルドが完了すると自動で `uvicorn` が起動し、`https://<your-space>.hf.space/mcp` で WebSocket が待ち受けます。
+4. ローカルまたは別サービスから WebSocket クライアントで接続すれば、手元と同じように動作確認できます。
+
+### 3. サーバー仕様メモ
+
+- HTTP `GET /` : ヘルスチェック用。`{"status": "ok"}` を返します。
+- WebSocket `/mcp` :
+  - 接続直後に `server_hello` を送信。
+  - `ping` / `tools.list` / `tool.call` のシンプルな 3 種類を実装。
+  - `tool.call` (`echo`) は `{"text": "..."} ` をそのまま返します。
+
+必要に応じて `mcp_endpoint` 内にツールを追加することで、独自の MCP サーバーとして発展させられます。

app.py

@@ -0,0 +1,96 @@
+"""
+Hugging Face Space friendly FastAPI application that exposes a minimal MCP-style
+WebSocket endpoint. It can be used to verify deployment and basic tool calls.
+"""
+
+import json
+from typing import Any, Dict
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import JSONResponse
+import uvicorn
+
+
+app = FastAPI(title="Sample MCP Server", version="0.1.0")
+
+
+@app.get("/")
+async def healthcheck() -> JSONResponse:
+    """Simple HTTP healthcheck so Spaces can mark the app as ready."""
+    return JSONResponse({"status": "ok", "message": "Sample MCP server is running."})
+
+
+@app.websocket("/mcp")
+async def mcp_endpoint(socket: WebSocket) -> None:
+    """
+    Minimal MCP-compatible WebSocket endpoint.
+
+    Protocol highlights:
+    - Sends a server hello message immediately after accepting a connection.
+    - Supports `ping` messages and a toy `echo` tool for demonstration.
+    """
+
+    await socket.accept()
+    await socket.send_json(
+        {
+            "type": "server_hello",
+            "version": "0.1.0",
+            "capabilities": ["ping", "tools.list", "tool.call"],
+        }
+    )
+
+    try:
+        while True:
+            raw = await socket.receive_text()
+            message: Dict[str, Any] = json.loads(raw)
+            kind = message.get("type")
+
+            if kind == "ping":
+                await socket.send_json({"type": "pong", "echo": message.get("payload")})
+            elif kind == "tools.list":
+                await socket.send_json(
+                    {
+                        "type": "tools",
+                        "tools": [
+                            {
+                                "name": "echo",
+                                "description": "Echoes back the provided text payload.",
+                            }
+                        ],
+                    }
+                )
+            elif kind == "tool.call":
+                tool_name = message.get("name")
+                request_id = message.get("id")
+                arguments = message.get("arguments", {})
+
+                if tool_name == "echo":
+                    await socket.send_json(
+                        {
+                            "type": "tool.result",
+                            "id": request_id,
+                            "result": {
+                                "text": arguments.get("text", ""),
+                            },
+                        }
+                    )
+                else:
+                    await socket.send_json(
+                        {
+                            "type": "error",
+                            "error": f"Unknown tool '{tool_name}'.",
+                            "id": request_id,
+                        }
+                    )
+            else:
+                await socket.send_json(
+                    {"type": "error", "error": f"Unsupported message type '{kind}'."}
+                )
+    except WebSocketDisconnect:
+        # Client disconnected; nothing else to do.
+        return
+
+
+if __name__ == "__main__":
+    uvicorn.run("app:app", host="0.0.0.0", port=7860, reload=False)
+

client.py

@@ -0,0 +1,55 @@
+"""
+Simple asyncio client to verify the sample MCP server.
+
+Usage:
+    python client.py --url ws://localhost:7860/mcp
+"""
+
+import argparse
+import asyncio
+import json
+from typing import Any, Dict
+
+import websockets
+
+
+async def run_client(url: str) -> None:
+    async with websockets.connect(url) as websocket:
+        hello_raw = await websocket.recv()
+        hello_message: Dict[str, Any] = json.loads(hello_raw)
+        print("hello:", hello_message)
+
+        await websocket.send(json.dumps({"type": "ping", "payload": "test"}))
+        print("pong :", await websocket.recv())
+
+        await websocket.send(json.dumps({"type": "tools.list"}))
+        print("tools:", await websocket.recv())
+
+        await websocket.send(
+            json.dumps(
+                {
+                    "type": "tool.call",
+                    "id": "demo-1",
+                    "name": "echo",
+                    "arguments": {"text": "Hello MCP"},
+                }
+            )
+        )
+        print("tool :", await websocket.recv())
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Sample MCP client")
+    parser.add_argument(
+        "--url",
+        default="ws://localhost:7860/mcp",
+        help="WebSocket endpoint of the MCP server.",
+    )
+    args = parser.parse_args()
+
+    asyncio.run(run_client(args.url))
+
+
+if __name__ == "__main__":
+    main()
+

requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.110.3
+uvicorn[standard]==0.30.1
+websockets==12.0