socratic-mcp 0.1.0__tar.gz

socratic_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 socratic-tutor contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

socratic_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: socratic-mcp
+Version: 0.1.0
+Summary: MCP server exposing a Socratic sidecar (kb_search, chapters, review) to any agent host
+Author: socratic-tutor contributors
+License: MIT
+Keywords: mcp,model-context-protocol,rag,citations,tutor
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# socratic-mcp
+
+把 Socratic sidecar 包成 **MCP server**：任何支持 MCP 的 agent host（DSH、Claude Desktop、Cursor…）都能直接调用，不需要为每个 host 写插件。
+
+```bash
+SOCRATIC_SIDECAR_URL=http://127.0.0.1:8765 python -m socratic_mcp.server
+```
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `kb_search` | 检索；返回 citation 与页图 URL；可带 `book`+`chapter` 收窄到章回 |
+| `kb_read` | 按 chunk_id 读取 |
+| `chapter_lookup` | 「卷3」「第7回」或标题片段 → 页码范围与页图；给 `page` 则反查所在章回 |
+| `review_session` | 复盘一个教学会话 |
+| `socratic_state` | 读教学状态机 |
+| `socratic_health` | sidecar 是否可达 + 索引统计 |
+
+## 配置
+
+| 环境变量 | 默认 | 说明 |
+|---|---|---|
+| `SOCRATIC_SIDECAR_URL` | `http://127.0.0.1:8765` | sidecar 地址 |
+| `SOCRATIC_TOKEN` | 空 | 非空时以 `Authorization: Bearer` 发送 |
+
+sidecar 未启动时，工具返回 `{"error":"sidecar_unreachable",...}` 且 `isError: true`，连接不断。
+
+## 挂到 DSH
+
+`~/.dsh/dsh-mcp-plus/servers.json` 加一条：
+
+```json
+{
+  "mcpServers": {
+    "socratic": {
+      "command": "python",
+      "args": ["-m", "socratic_mcp.server"],
+      "env": { "SOCRATIC_SIDECAR_URL": "http://127.0.0.1:8765" }
+    }
+  }
+}
+```
+
+## 协议实现范围
+
+`initialize`、`ping`、`tools/list`、`tools/call`，stdio + newline-delimited JSON-RPC 2.0。没有 SDK 依赖（6 条测试，含一次真实 stdio 往返）。

socratic_mcp-0.1.0/README.md

@@ -0,0 +1,47 @@
+# socratic-mcp
+
+把 Socratic sidecar 包成 **MCP server**：任何支持 MCP 的 agent host（DSH、Claude Desktop、Cursor…）都能直接调用，不需要为每个 host 写插件。
+
+```bash
+SOCRATIC_SIDECAR_URL=http://127.0.0.1:8765 python -m socratic_mcp.server
+```
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `kb_search` | 检索；返回 citation 与页图 URL；可带 `book`+`chapter` 收窄到章回 |
+| `kb_read` | 按 chunk_id 读取 |
+| `chapter_lookup` | 「卷3」「第7回」或标题片段 → 页码范围与页图；给 `page` 则反查所在章回 |
+| `review_session` | 复盘一个教学会话 |
+| `socratic_state` | 读教学状态机 |
+| `socratic_health` | sidecar 是否可达 + 索引统计 |
+
+## 配置
+
+| 环境变量 | 默认 | 说明 |
+|---|---|---|
+| `SOCRATIC_SIDECAR_URL` | `http://127.0.0.1:8765` | sidecar 地址 |
+| `SOCRATIC_TOKEN` | 空 | 非空时以 `Authorization: Bearer` 发送 |
+
+sidecar 未启动时，工具返回 `{"error":"sidecar_unreachable",...}` 且 `isError: true`，连接不断。
+
+## 挂到 DSH
+
+`~/.dsh/dsh-mcp-plus/servers.json` 加一条：
+
+```json
+{
+  "mcpServers": {
+    "socratic": {
+      "command": "python",
+      "args": ["-m", "socratic_mcp.server"],
+      "env": { "SOCRATIC_SIDECAR_URL": "http://127.0.0.1:8765" }
+    }
+  }
+}
+```
+
+## 协议实现范围
+
+`initialize`、`ping`、`tools/list`、`tools/call`，stdio + newline-delimited JSON-RPC 2.0。没有 SDK 依赖（6 条测试，含一次真实 stdio 往返）。

socratic_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "socratic-mcp"
+version = "0.1.0"
+description = "MCP server exposing a Socratic sidecar (kb_search, chapters, review) to any agent host"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "socratic-tutor contributors" }]
+keywords = ["mcp", "model-context-protocol", "rag", "citations", "tutor"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Education",
+]
+license = { text = "MIT" }
+dependencies = []
+
+[project.scripts]
+socratic-mcp = "socratic_mcp.server:main"
+
+[tool.setuptools]
+packages = ["socratic_mcp"]

socratic_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

socratic_mcp-0.1.0/socratic_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server for a Socratic sidecar (stdlib only)."""
+
+from . import tools  # noqa: F401
+
+__version__ = "0.1.0"

socratic_mcp-0.1.0/socratic_mcp/server.py

@@ -0,0 +1,76 @@
+"""Minimal MCP server over stdio (JSON-RPC 2.0, newline-delimited).
+
+  python -m socratic_mcp.server            # uses SOCRATIC_SIDECAR_URL / SOCRATIC_TOKEN
+
+Speaks just enough of the protocol for an agent host: initialize, tools/list,
+tools/call, ping. No third-party dependencies.
+"""
+import json
+import sys
+
+from . import tools
+
+
+def _ok(mid, result):
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def _err(mid, code, message):
+    return {"jsonrpc": "2.0", "id": mid, "error": {"code": code, "message": message}}
+
+
+def handle(msg):
+    """One request -> one response (or None for notifications)."""
+    method = msg.get("method")
+    mid = msg.get("id")
+    if mid is None:                                  # notification
+        return None
+    if method == "initialize":
+        return _ok(mid, {
+            "protocolVersion": tools.PROTOCOL,
+            "capabilities": {"tools": {"listChanged": False}},
+            "serverInfo": {"name": "socratic-sidecar", "version": tools.VERSION},
+        })
+    if method == "ping":
+        return _ok(mid, {})
+    if method == "tools/list":
+        return _ok(mid, {"tools": tools.TOOLS})
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        name = params.get("name")
+        args = params.get("arguments") or {}
+        if not any(t["name"] == name for t in tools.TOOLS):
+            return _err(mid, -32602, "unknown tool: %s" % name)
+        try:
+            result = tools.call_tool(name, args)
+        except KeyError as e:
+            return _err(mid, -32602, "bad arguments for %s: %s" % (name, e))
+        except Exception as e:  # never crash the transport on one bad call
+            return _err(mid, -32603, str(e)[:200])
+        failed = isinstance(result, dict) and result.get("ok") is False
+        return _ok(mid, {"content": [{"type": "text",
+                                      "text": json.dumps(result, ensure_ascii=False)}],
+                         "isError": bool(failed)})
+    return _err(mid, -32601, "method not found: %s" % method)
+
+
+def main():
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            msg = json.loads(line)
+        except Exception:
+            sys.stdout.write(json.dumps(_err(None, -32700, "parse error")) + "\n")
+            sys.stdout.flush()
+            continue
+        out = handle(msg)
+        if out is not None:
+            sys.stdout.write(json.dumps(out, ensure_ascii=False) + "\n")
+            sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

socratic_mcp-0.1.0/socratic_mcp/tools.py

@@ -0,0 +1,165 @@
+"""MCP tools that expose a Socratic sidecar.
+
+The contract is the sidecar's HTTP API (docs/SIDECAR-CONTRACT.md); this module
+only translates MCP tool calls into requests and wraps the JSON back into
+content blocks. No MCP SDK: the stdio protocol is small enough to speak
+directly, which keeps the package dependency-free.
+"""
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+
+PROTOCOL = "2024-11-05"
+VERSION = "0.1.0"
+
+TOOLS = [
+    {
+        "name": "kb_search",
+        "description": "Search the book library; returns citations and page-image URLs. "
+                       "Use book+chapter to narrow to one chapter of a scanned book.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "view": {"type": "string", "enum": ["student", "tutor"]},
+                "limit": {"type": "integer", "minimum": 1, "maximum": 20},
+                "source": {"type": "string"},
+                "lang": {"type": "string"},
+                "book": {"type": "string"},
+                "chapter": {"type": "string"},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "kb_read",
+        "description": "Read one chunk by id (citation included).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"chunk_id": {"type": "integer"}, "view": {"type": "string"}},
+            "required": ["chunk_id"],
+        },
+    },
+    {
+        "name": "chapter_lookup",
+        "description": "Resolve '卷3' / '第7回' / a title fragment to a page range and page images; "
+                       "pass page to find which chapter contains it.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "book": {"type": "string"},
+                "chapter": {"type": "string"},
+                "page": {"type": "integer", "minimum": 1},
+                "source": {"type": "string"},
+            },
+            "required": ["book"],
+        },
+    },
+    {
+        "name": "review_session",
+        "description": "Freeze a tutoring session and review it: claim verdicts, error classes, practice.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "answers": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["session_id"],
+        },
+    },
+    {
+        "name": "socratic_state",
+        "description": "Read the teaching state machine state for a session.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"session_id": {"type": "string"}},
+            "required": ["session_id"],
+        },
+    },
+    {
+        "name": "socratic_health",
+        "description": "Whether the sidecar is reachable, plus index statistics.",
+        "inputSchema": {"type": "object", "properties": {}},
+    },
+]
+
+
+def base_url():
+    return os.environ.get("SOCRATIC_SIDECAR_URL", "http://127.0.0.1:8765").rstrip("/")
+
+
+def _headers():
+    token = os.environ.get("SOCRATIC_TOKEN", "")
+    return {"Authorization": "Bearer " + token} if token else {}
+
+
+def _get(path):
+    req = urllib.request.Request(base_url() + path, headers=_headers())
+    try:
+        with urllib.request.urlopen(req, timeout=60) as r:
+            return json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        body = {}
+        try:
+            body = json.loads(e.read() or b"{}")
+        except Exception:
+            pass
+        return {"ok": False, "status": e.code, "body": body}
+    except Exception as e:  # connection refused, DNS, timeout
+        return {"ok": False, "error": "sidecar_unreachable", "detail": str(e)[:200],
+                "base": base_url()}
+
+
+def _post(path, payload):
+    data = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(base_url() + path, data=data, headers={
+        "Content-Type": "application/json", **_headers()})
+    try:
+        with urllib.request.urlopen(req, timeout=120) as r:
+            return json.loads(r.read() or b"{}")
+    except urllib.error.HTTPError as e:
+        body = {}
+        try:
+            body = json.loads(e.read() or b"{}")
+        except Exception:
+            pass
+        return {"ok": False, "status": e.code, "body": body}
+    except Exception as e:
+        return {"ok": False, "error": "sidecar_unreachable", "detail": str(e)[:200],
+                "base": base_url()}
+
+
+def call_tool(name, args):
+    """Map one MCP tool call to the sidecar and return a JSON-able result."""
+    if name == "kb_search":
+        q = {"q": str(args.get("query", "")),
+             "view": str(args.get("view", "student")),
+             "limit": str(args.get("limit", 8))}
+        for key in ("source", "lang", "book", "chapter"):
+            if args.get(key):
+                q[key] = str(args[key])
+        return _get("/v1/search?" + urllib.parse.urlencode(q))
+    if name == "kb_read":
+        q = {"view": str(args.get("view", "student"))}
+        return _get("/v1/chunks/%d?%s" % (int(args["chunk_id"]), urllib.parse.urlencode(q)))
+    if name == "chapter_lookup":
+        q = {"book": str(args["book"])}
+        if args.get("source"):
+            q["source"] = str(args["source"])
+        if args.get("chapter"):
+            q["q"] = str(args["chapter"])
+        if args.get("page"):
+            q["page"] = str(args["page"])
+        return _get("/v1/chapter?" + urllib.parse.urlencode(q))
+    if name == "review_session":
+        body = {"session_id": str(args["session_id"])}
+        if args.get("answers"):
+            body["answers"] = [str(a) for a in args["answers"]]
+        return _post("/v1/review", body)
+    if name == "socratic_state":
+        return _get("/v1/state/" + urllib.parse.quote(str(args["session_id"])))
+    if name == "socratic_health":
+        return _get("/health")
+    raise KeyError(name)

socratic_mcp-0.1.0/socratic_mcp.egg-info/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: socratic-mcp
+Version: 0.1.0
+Summary: MCP server exposing a Socratic sidecar (kb_search, chapters, review) to any agent host
+Author: socratic-tutor contributors
+License: MIT
+Keywords: mcp,model-context-protocol,rag,citations,tutor
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Education
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# socratic-mcp
+
+把 Socratic sidecar 包成 **MCP server**：任何支持 MCP 的 agent host（DSH、Claude Desktop、Cursor…）都能直接调用，不需要为每个 host 写插件。
+
+```bash
+SOCRATIC_SIDECAR_URL=http://127.0.0.1:8765 python -m socratic_mcp.server
+```
+
+## 工具
+
+| 工具 | 作用 |
+|---|---|
+| `kb_search` | 检索；返回 citation 与页图 URL；可带 `book`+`chapter` 收窄到章回 |
+| `kb_read` | 按 chunk_id 读取 |
+| `chapter_lookup` | 「卷3」「第7回」或标题片段 → 页码范围与页图；给 `page` 则反查所在章回 |
+| `review_session` | 复盘一个教学会话 |
+| `socratic_state` | 读教学状态机 |
+| `socratic_health` | sidecar 是否可达 + 索引统计 |
+
+## 配置
+
+| 环境变量 | 默认 | 说明 |
+|---|---|---|
+| `SOCRATIC_SIDECAR_URL` | `http://127.0.0.1:8765` | sidecar 地址 |
+| `SOCRATIC_TOKEN` | 空 | 非空时以 `Authorization: Bearer` 发送 |
+
+sidecar 未启动时，工具返回 `{"error":"sidecar_unreachable",...}` 且 `isError: true`，连接不断。
+
+## 挂到 DSH
+
+`~/.dsh/dsh-mcp-plus/servers.json` 加一条：
+
+```json
+{
+  "mcpServers": {
+    "socratic": {
+      "command": "python",
+      "args": ["-m", "socratic_mcp.server"],
+      "env": { "SOCRATIC_SIDECAR_URL": "http://127.0.0.1:8765" }
+    }
+  }
+}
+```
+
+## 协议实现范围
+
+`initialize`、`ping`、`tools/list`、`tools/call`，stdio + newline-delimited JSON-RPC 2.0。没有 SDK 依赖（6 条测试，含一次真实 stdio 往返）。

socratic_mcp-0.1.0/socratic_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+socratic_mcp/__init__.py
+socratic_mcp/server.py
+socratic_mcp/tools.py
+socratic_mcp.egg-info/PKG-INFO
+socratic_mcp.egg-info/SOURCES.txt
+socratic_mcp.egg-info/dependency_links.txt
+socratic_mcp.egg-info/entry_points.txt
+socratic_mcp.egg-info/top_level.txt
+tests/test_server.py

socratic_mcp-0.1.0/socratic_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

socratic_mcp-0.1.0/socratic_mcp.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+socratic-mcp = socratic_mcp.server:main

socratic_mcp-0.1.0/socratic_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+socratic_mcp

socratic_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,62 @@
+import json
+import subprocess
+import sys
+import unittest
+
+from socratic_mcp import server, tools
+
+
+class TestProtocol(unittest.TestCase):
+    def test_initialize(self):
+        out = server.handle({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}})
+        self.assertEqual(out["result"]["protocolVersion"], tools.PROTOCOL)
+        self.assertIn("tools", out["result"]["capabilities"])
+
+    def test_tools_list(self):
+        out = server.handle({"jsonrpc": "2.0", "id": 2, "method": "tools/list"})
+        names = [t["name"] for t in out["result"]["tools"]]
+        for want in ("kb_search", "kb_read", "chapter_lookup", "review_session", "socratic_health"):
+            self.assertIn(want, names)
+
+    def test_unknown_tool(self):
+        out = server.handle({"jsonrpc": "2.0", "id": 3, "method": "tools/call",
+                             "params": {"name": "nope", "arguments": {}}})
+        self.assertEqual(out["error"]["code"], -32602)
+
+    def test_notification_has_no_response(self):
+        self.assertIsNone(server.handle({"jsonrpc": "2.0", "method": "notifications/initialized"}))
+
+    def test_unreachable_sidecar_is_a_tool_error_not_a_crash(self):
+        old = tools.os.environ.get("SOCRATIC_SIDECAR_URL")
+        tools.os.environ["SOCRATIC_SIDECAR_URL"] = "http://127.0.0.1:9"
+        try:
+            out = server.handle({"jsonrpc": "2.0", "id": 4, "method": "tools/call",
+                                 "params": {"name": "socratic_health", "arguments": {}}})
+            self.assertTrue(out["result"]["isError"])
+            body = json.loads(out["result"]["content"][0]["text"])
+            self.assertEqual(body["error"], "sidecar_unreachable")
+        finally:
+            if old is None:
+                tools.os.environ.pop("SOCRATIC_SIDECAR_URL", None)
+            else:
+                tools.os.environ["SOCRATIC_SIDECAR_URL"] = old
+
+
+class TestStdio(unittest.TestCase):
+    def test_roundtrip_over_stdio(self):
+        proc = subprocess.Popen([sys.executable, "-m", "socratic_mcp.server"],
+                                stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                                stderr=subprocess.DEVNULL, text=True)
+        try:
+            proc.stdin.write(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "initialize"}) + "\n")
+            proc.stdin.flush()
+            line = proc.stdout.readline()
+            self.assertIn("protocolVersion", json.loads(line)["result"])
+        finally:
+            proc.kill()
+            for stream in (proc.stdin, proc.stdout):
+                try:
+                    stream.close()
+                except Exception:
+                    pass
+            proc.wait(timeout=5)