gramfig-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gramfig
+
+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.

package/README.md

@@ -1,3 +1,107 @@
-# Temporary Holding Version
+# gramfig-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+图数学堂（Gramfig）的本地 MCP 服务。通过 **stdio** 向 AI 客户端提供 LaTeX 公式渲染、函数图像绘制与平面几何工具，不依赖浏览器、网络或云端状态。
+
+> A stateless MCP stdio server for LaTeX rendering, function plotting, and plane geometry documents.
+
+## 快速开始
+
+要求 Node.js 22+：
+
+```bash
+npx -y gramfig-mcp
+```
+
+在支持 stdio 的 MCP 客户端中配置：
+
+```json
+{
+  "mcpServers": {
+    "gramfig": {
+      "command": "npx",
+      "args": ["-y", "gramfig-mcp"]
+    }
+  }
+}
+```
+
+服务启动日志只写入 stderr，stdout 专用于 MCP 协议帧。
+
+## 工具
+
+| 工具 | 用途 |
+|---|---|
+| `latex_render` | LaTeX 数学/化学公式 → 安全 HTML 或小程序 rich-text nodes |
+| `graph_plot` | mathjs 表达式 → SVG/PNG 函数图像 |
+| `geometry_solve` | 校验并求解 `protocolVersion: 1` 平面几何文档 |
+| `geometry_measure` | 读取或临时查询长度、周长、面积、角度 |
+| `geometry_render` | 纯几何文档 → SVG/PNG（含 LaTeX 标注） |
+
+### latex_render
+
+```json
+{
+  "latex": "\\frac{a}{b}",
+  "displayMode": false,
+  "outputs": ["html"]
+}
+```
+
+数学公式走 KaTeX，`\ce{}` 化学公式自动分流 MathJax；HTML 经过白名单清洗。`latex` 上限 4096 字符。
+
+### graph_plot
+
+```json
+{
+  "expressions": [
+    { "raw": "sin(x)", "label": "sin" },
+    { "raw": "x^2", "label": "x²", "color": "#dc2626" }
+  ],
+  "viewport": { "xMin": -6, "xMax": 6, "yMin": -4, "yMax": 4 },
+  "format": "svg"
+}
+```
+
+支持 1–8 条曲线，单条表达式 ≤ 200 字符；可输出 SVG 或 base64 PNG，支持 light/dark 主题。
+
+### geometry_solve / geometry_measure / geometry_render
+
+```json
+{
+  "protocolVersion": 1,
+  "elements": [
+    { "id": "a", "type": "point", "position": [0, 0] },
+    { "id": "b", "type": "point", "position": [2, 0] },
+    { "id": "s", "type": "segment", "parents": ["a", "b"] }
+  ],
+  "viewport": { "xMin": -3, "xMax": 3, "yMin": -2, "yMax": 2, "keepAspectRatio": true }
+}
+```
+
+推荐链路：`geometry_solve` 自检并修正文档 → `geometry_measure` 取测量值 → `geometry_render` 输出图像。几何工具仅接受纯几何 v1 文档，v2/含函数方程文档请使用 `graph_plot`。
+
+完整协议、变换/轨迹、限额与错误码见 [docs/mcp-geometry.md](https://github.com/gaorock530/studylab/blob/main/docs/mcp-geometry.md)。
+
+## 限制
+
+- 几何文档 JSON ≤ 512KB，元素数 ≤ 500
+- 测量查询 ≤ 50 条；轨迹采样 16–400、总量 ≤ 100000
+- 画布尺寸 200–2000 px；PNG base64 ≤ 8MB
+- 服务不读写文件、不访问网络、不保存会话状态
+
+错误码：`INVALID_DOCUMENT`、`DUPLICATE_ID`、`UNKNOWN_PARENT`、`CYCLE`、`DEGENERATE`、`UNSUPPORTED_TYPE`、`UNSUPPORTED_CURVE_DEPENDENT`、`UNSUPPORTED_DOCUMENT`、`LIMIT_EXCEEDED`、`RENDER_FAILED`。
+
+## 开发
+
+```bash
+corepack pnpm --filter gramfig-mcp typecheck
+corepack pnpm --filter gramfig-mcp test
+corepack pnpm --filter gramfig-mcp build
+corepack pnpm --filter gramfig-mcp pack
+```
+
+`prepack` 会先构建 `@studylab/formula`、`@studylab/viz`，再用 esbuild 把内部包内联为单个 `dist/main.js`；`@resvg/resvg-js`、`jsdom`、KaTeX/MathJax 等保持为运行时依赖。
+
+## License
+
+[MIT](./LICENSE)