mofox-docs-mcp 0.1.0__tar.gz

mofox_docs_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mofox_docs_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+*.log
+.DS_Store

mofox_docs_mcp-0.1.0/LICENSE

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

mofox_docs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: mofox-docs-mcp
+Version: 0.1.0
+Summary: Neo-MoFox 官方文档 MCP 服务器：通过 Model Context Protocol 搜索与阅读 MoFox-Bot-Docs 文档
+Project-URL: Homepage, https://github.com/minecraft1024a/mofox-docs-mcp
+Project-URL: Documentation, https://docs.mofox-sama.com
+Author: minecraft1024a
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docs,documentation,mcp,mcp-server,model-context-protocol,mofox,neo-mofox
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2
+Description-Content-Type: text/markdown
+
+# mofox-docs-mcp
+
+Neo-MoFox 官方文档 MCP 服务器：通过 [Model Context Protocol](https://modelcontextprotocol.io) 提供 MoFox-Bot-Docs 文档站的检索与阅读能力，供 Claude、Cursor、Neo-MoFox 等 MCP 客户端直接搜索与阅读官方文档。
+
+数据源为文档站 JSON API（`https://docs.mofox-sama.com/api/docs/*`），与 MoFox 插件市场中的 `mofox_docs` 插件共用同一套 `llms.json` 索引，行为一致。
+
+## 功能
+
+### 工具 Tools
+
+| 工具 | 说明 |
+| --- | --- |
+| `search_docs(query, limit?, offset?)` | 按关键词检索文档。查询按空白拆词，按「命中关键词数量」降序返回（如 `"Windows 部署 安装"` 会优先命中 `guides/deployment/deployment_guide`）。支持分页 |
+| `list_docs(limit?, offset?)` | 列出文档。按 section 排序，部署指南（`guides/deployment`）排最前，每篇含 title / description / preview / section |
+| `get_doc(doc_id)` | 获取指定文档完整正文（纯文本）。`doc_id` 形如 `guides/deployment/deployment_guide` |
+
+### 资源 Resources
+
+| 资源 | 说明 |
+| --- | --- |
+| `mofox://docs` | 全量索引（`llms.json`，含每篇的标题 / 简介 / 正文预览） |
+| `mofox://docs/{id}` | 单篇文档完整内容（如 `mofox://docs/guides/configuration/bot_config_guide`） |
+
+## 快速开始
+
+### 方式一：uvx 直接运行（推荐）
+
+```bash
+uvx mofox-docs-mcp
+```
+
+或使用 pipx：
+
+```bash
+pipx run mofox-docs-mcp
+```
+
+### 方式二：pip 安装后运行
+
+```bash
+pip install mofox-docs-mcp
+mofox-docs-mcp
+```
+
+### 方式三：克隆 / 本地构建
+
+```bash
+uv sync            # 或 pip install -e .
+uv run mofox-docs-mcp
+```
+
+## 接入 Neo-MoFox
+
+编辑 `config/mcp.toml`：
+
+```toml
+[mcp.stdio_servers.mofox-docs]
+command = "uvx"
+args = ["mofox-docs-mcp"]
+instructions = "提供 Neo-MoFox 官方文档的搜索与阅读功能，当用户询问框架功能、配置、插件开发、API 用法时使用"
+```
+
+重启 Neo-MoFox 即可生效。
+
+## 其他 MCP 客户端
+
+```json
+{
+  "mcpServers": {
+    "mofox-docs": {
+      "command": "uvx",
+      "args": ["mofox-docs-mcp"]
+    }
+  }
+}
+```
+
+## 配置选项
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `--base-url <url>` | 文档站地址 | `https://docs.mofox-sama.com` |
+| `--timeout <秒>` | 请求超时 | `30` |
+| `--cache-ttl <秒>` | 索引缓存时长（`llms.json`） | `300` |
+
+也支持同名环境变量：`MOFOX_DOCS_BASE_URL`、`MOFOX_DOCS_TIMEOUT`、`MOFOX_DOCS_CACHE_TTL`。
+
+## 开发
+
+```bash
+uv sync               # 创建虚拟环境并安装依赖
+uv run mofox-docs-mcp # 运行服务器
+uv build              # 构建 sdist / wheel 到 dist/
+```
+
+## License
+
+MIT

mofox_docs_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,126 @@
+# 发布指南：PyPI
+
+本目录是 `mofox-docs-mcp` MCP 服务器 Python 源码。以下步骤帮你把它发布到 **PyPI**（`uvx mofox-docs-mcp` / `pip install mofox-docs-mcp` 直接可用）。
+
+> 发布需要你自己的 PyPI 账号凭证，因此这里只提供操作指引。
+
+---
+
+## 0. 前置检查
+
+```bash
+python3 --version   # 需要 >= 3.10
+uv --version        # https://docs.astral.sh/uv/
+```
+
+发布前先本地验证一遍：
+
+```bash
+uv sync                 # 创建 .venv 并安装依赖（含本包，可编辑模式）
+uv run mofox-docs-mcp   # 能正常启动（Ctrl+C 退出）即 OK
+```
+
+确认 `pyproject.toml`：
+
+- `name`: `mofox-docs-mcp`（已确认 PyPI 上未被占用）
+- `version`: `0.1.0`
+
+---
+
+## 1. 构建
+
+```bash
+uv build    # 生成 dist/mofox_docs_mcp-*.tar.gz 与 dist/mofox_docs_mcp-*.whl
+```
+
+发布前可用 [TestPyPI](htt.ps://test.pypi.org) 预演：
+
+```bash
+uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-xxxx
+```
+
+---
+
+## 2. 登录并发布到 PyPI
+
+### 方式 A：API Token（推荐）
+
+1. 在 <https://pypi.org/manage/account/token/> 创建一个 API Token（范围可选限定到本项目）。
+2. 发布：
+
+```bash
+uv publish --token pypi-xxxx
+```
+
+或用环境变量：
+
+```bash
+UV_PUBLISH_TOKEN=pypi-xxxx uv publish
+```
+
+### 方式 B：trusted publishing（GitHub Actions 自动发布）
+
+在 PyPI 项目设置中配置 GitHub Trusted Publisher 后，推送 tag 时由 CI 调用 `uv publish`，无需手动 token。
+
+### 验证
+
+```bash
+uvx mofox-docs-mcp --help
+```
+
+能打印帮助即发布成功。任何 MCP 客户端现在都可以：
+
+```bash
+uvx mofox-docs-mcp
+```
+
+---
+
+## 3. 后续更新版本
+
+改完代码后按语义化版本升级并重新发布：
+
+```bash
+# 手动把 pyproject.toml 与 src/mofox_docs_mcp/__init__.py 的 __version__ 同步升级
+# 0.1.0 -> 0.1.1（patch）或 minor / major
+uv build && uv publish --token pypi-xxxx
+git tag v0.1.1 && git push origin master --tags
+```
+
+---
+
+## 4. 接入 Neo-MoFox
+
+发布成功后，在 Neo-MoFox 的 `config/mcp.toml` 添加：
+
+```toml
+[mcp.stdio_servers.mofox-docs]
+command = "uvx"
+args = ["mofox-docs-mcp"]
+instructions = "提供 Neo-MoFox 官方文档的搜索与阅读功能，当用户询问框架功能、配置、插件开发、API 用法时使用"
+```
+
+---
+
+## 5. 常见问题
+
+| 现象 | 原因 / 解决 |
+| --- | --- |
+| `uv publish` 报 403 | 未带 token 或 token 无权限：先在 PyPI 创建/更新 API Token |
+| 报 "File already exists" / 版本冲突 | 版本号未递增：升级 `pyproject.toml` 与 `__init__.py` 的 version 后再发 |
+| `uvx` 还是旧版本 | 清缓存：`uv cache clean mofox-docs-mcp` 或指定 `mofox-docs-mcp==x.y.z` |
+| 包名被占用 | 换名；PyPI 上 `mofox-docs-mcp` 归先注册者所有 |
+| `git push` 被拒 | 先 `git pull --rebase origin master` 再推 |
+
+---
+
+## 6. 仓库内文件说明
+
+| 文件 | 说明 |
+| --- | --- |
+| `src/mofox_docs_mcp/server.py` | MCP 服务器源码（3 个工具 + 2 类资源 + CLI 解析） |
+| `src/mofox_docs_mcp/__init__.py` | 包元数据与版本号 |
+| `src/mofox_docs_mcp/__main__.py` | `python -m mofox_docs_mcp` 入口 |
+| `pyproject.toml` | PyPI 包配置（依赖 / 入口脚本 / 构建后端） |
+| `README.md` | 使用文档（会随包发布） |
+| `dist/` | 构建产物（`uv build` 生成，勿手改） |

mofox_docs_mcp-0.1.0/README.md

@@ -0,0 +1,98 @@
+# mofox-docs-mcp
+
+Neo-MoFox 官方文档 MCP 服务器：通过 [Model Context Protocol](https://modelcontextprotocol.io) 提供 MoFox-Bot-Docs 文档站的检索与阅读能力，供 Claude、Cursor、Neo-MoFox 等 MCP 客户端直接搜索与阅读官方文档。
+
+数据源为文档站 JSON API（`https://docs.mofox-sama.com/api/docs/*`），与 MoFox 插件市场中的 `mofox_docs` 插件共用同一套 `llms.json` 索引，行为一致。
+
+## 功能
+
+### 工具 Tools
+
+| 工具 | 说明 |
+| --- | --- |
+| `search_docs(query, limit?, offset?)` | 按关键词检索文档。查询按空白拆词，按「命中关键词数量」降序返回（如 `"Windows 部署 安装"` 会优先命中 `guides/deployment/deployment_guide`）。支持分页 |
+| `list_docs(limit?, offset?)` | 列出文档。按 section 排序，部署指南（`guides/deployment`）排最前，每篇含 title / description / preview / section |
+| `get_doc(doc_id)` | 获取指定文档完整正文（纯文本）。`doc_id` 形如 `guides/deployment/deployment_guide` |
+
+### 资源 Resources
+
+| 资源 | 说明 |
+| --- | --- |
+| `mofox://docs` | 全量索引（`llms.json`，含每篇的标题 / 简介 / 正文预览） |
+| `mofox://docs/{id}` | 单篇文档完整内容（如 `mofox://docs/guides/configuration/bot_config_guide`） |
+
+## 快速开始
+
+### 方式一：uvx 直接运行（推荐）
+
+```bash
+uvx mofox-docs-mcp
+```
+
+或使用 pipx：
+
+```bash
+pipx run mofox-docs-mcp
+```
+
+### 方式二：pip 安装后运行
+
+```bash
+pip install mofox-docs-mcp
+mofox-docs-mcp
+```
+
+### 方式三：克隆 / 本地构建
+
+```bash
+uv sync            # 或 pip install -e .
+uv run mofox-docs-mcp
+```
+
+## 接入 Neo-MoFox
+
+编辑 `config/mcp.toml`：
+
+```toml
+[mcp.stdio_servers.mofox-docs]
+command = "uvx"
+args = ["mofox-docs-mcp"]
+instructions = "提供 Neo-MoFox 官方文档的搜索与阅读功能，当用户询问框架功能、配置、插件开发、API 用法时使用"
+```
+
+重启 Neo-MoFox 即可生效。
+
+## 其他 MCP 客户端
+
+```json
+{
+  "mcpServers": {
+    "mofox-docs": {
+      "command": "uvx",
+      "args": ["mofox-docs-mcp"]
+    }
+  }
+}
+```
+
+## 配置选项
+
+| 参数 | 说明 | 默认值 |
+| --- | --- | --- |
+| `--base-url <url>` | 文档站地址 | `https://docs.mofox-sama.com` |
+| `--timeout <秒>` | 请求超时 | `30` |
+| `--cache-ttl <秒>` | 索引缓存时长（`llms.json`） | `300` |
+
+也支持同名环境变量：`MOFOX_DOCS_BASE_URL`、`MOFOX_DOCS_TIMEOUT`、`MOFOX_DOCS_CACHE_TTL`。
+
+## 开发
+
+```bash
+uv sync               # 创建虚拟环境并安装依赖
+uv run mofox-docs-mcp # 运行服务器
+uv build              # 构建 sdist / wheel 到 dist/
+```
+
+## License
+
+MIT

mofox_docs_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mofox-docs-mcp"
+version = "0.1.0"
+description = "Neo-MoFox 官方文档 MCP 服务器：通过 Model Context Protocol 搜索与阅读 MoFox-Bot-Docs 文档"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "minecraft1024a" }]
+requires-python = ">=3.10"
+keywords = [
+  "mcp",
+  "mcp-server",
+  "model-context-protocol",
+  "mofox",
+  "neo-mofox",
+  "docs",
+  "documentation",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+  "mcp>=2,<3",
+  "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://github.com/minecraft1024a/mofox-docs-mcp"
+Documentation = "https://docs.mofox-sama.com"
+
+[project.scripts]
+mofox-docs-mcp = "mofox_docs_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mofox_docs_mcp"]

mofox_docs_mcp-0.1.0/src/mofox_docs_mcp/__init__.py

@@ -0,0 +1,15 @@
+# mofox-docs-mcp — Neo-MoFox 官方文档 MCP 服务器
+#
+# 通过 Model Context Protocol 提供 MoFox-Bot-Docs 文档站的检索与阅读能力：
+#   - 工具：search_docs / list_docs / get_doc
+#   - 资源：mofox://docs（全量索引）、mofox://docs/<id>（单篇正文）
+#
+# 数据源为文档站 JSON API（https://docs.mofox-sama.com/api/docs/*），
+# 与 MoFox 插件市场中的 mofox_docs 插件共用同一套索引（llms.json）。
+"""Neo-MoFox 官方文档 MCP 服务器。"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mofox_docs_mcp-0.1.0/src/mofox_docs_mcp/__main__.py

@@ -0,0 +1,8 @@
+"""python -m mofox_docs_mcp 入口。"""
+
+from __future__ import annotations
+
+from .server import main
+
+if __name__ == "__main__":
+    main()