doc-toolkit-mcp 0.1.0__tar.gz

doc_toolkit_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 B2B增长工坊
+
+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.

doc_toolkit_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.5
+Name: doc-toolkit-mcp
+Version: 0.1.0
+Summary: MCP server for local document work: convert to Markdown, OCR scanned files, chunk for retrieval, and split or merge PDFs
+Project-URL: Homepage, https://open.workbuddy.cn
+Author: B2B增长工坊
+License: MIT
+License-File: LICENSE
+Keywords: markdown,mcp,ocr,pdf,rag
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: jieba>=0.42
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: pypdf>=4.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-pptx>=0.6.23
+Provides-Extra: ocr
+Requires-Dist: rapidocr-onnxruntime>=1.3; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# doc-toolkit-mcp
+
+MCP server for local document work. **Everything runs on your machine** — no upload, no API key, no account.
+
+| Tool | What it does |
+|---|---|
+| `convert_to_markdown` | PDF / DOCX / PPTX / XLSX → Markdown, tables preserved |
+| `ocr_extract` | Images and scanned PDFs → text (optional OCR extra) |
+| `split_chunks` | Split a document into retrieval-sized chunks |
+| `pdf_merge` | Merge several PDFs in order |
+| `pdf_split` | Split by page count, or extract a page range |
+
+## Install
+
+```bash
+uvx doc-toolkit-mcp
+```
+
+With OCR support:
+
+```bash
+uvx --with rapidocr-onnxruntime doc-toolkit-mcp
+```
+
+## MCP client config
+
+```json
+{
+  "mcpServers": {
+    "doc-toolkit": {
+      "command": "uvx",
+      "args": ["doc-toolkit-mcp"]
+    }
+  }
+}
+```
+
+## Behaviour notes
+
+- `convert_to_markdown` reads the text layer only; scanned PDFs come back empty and should go through `ocr_extract`.
+- `ocr_extract` checks each PDF page for a text layer first and only OCRs pages that lack one.
+- `split_chunks` keeps the nearest heading with every chunk so retrieved passages carry context.
+- All paths are absolute paths on the machine running the client.
+
+## License
+
+MIT

doc_toolkit_mcp-0.1.0/README.md

@@ -0,0 +1,47 @@
+# doc-toolkit-mcp
+
+MCP server for local document work. **Everything runs on your machine** — no upload, no API key, no account.
+
+| Tool | What it does |
+|---|---|
+| `convert_to_markdown` | PDF / DOCX / PPTX / XLSX → Markdown, tables preserved |
+| `ocr_extract` | Images and scanned PDFs → text (optional OCR extra) |
+| `split_chunks` | Split a document into retrieval-sized chunks |
+| `pdf_merge` | Merge several PDFs in order |
+| `pdf_split` | Split by page count, or extract a page range |
+
+## Install
+
+```bash
+uvx doc-toolkit-mcp
+```
+
+With OCR support:
+
+```bash
+uvx --with rapidocr-onnxruntime doc-toolkit-mcp
+```
+
+## MCP client config
+
+```json
+{
+  "mcpServers": {
+    "doc-toolkit": {
+      "command": "uvx",
+      "args": ["doc-toolkit-mcp"]
+    }
+  }
+}
+```
+
+## Behaviour notes
+
+- `convert_to_markdown` reads the text layer only; scanned PDFs come back empty and should go through `ocr_extract`.
+- `ocr_extract` checks each PDF page for a text layer first and only OCRs pages that lack one.
+- `split_chunks` keeps the nearest heading with every chunk so retrieved passages carry context.
+- All paths are absolute paths on the machine running the client.
+
+## License
+
+MIT

doc_toolkit_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "doc-toolkit-mcp"
+version = "0.1.0"
+description = "MCP server for local document work: convert to Markdown, OCR scanned files, chunk for retrieval, and split or merge PDFs"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "B2B增长工坊" }]
+keywords = ["mcp", "pdf", "ocr", "markdown", "rag"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "mcp>=1.2.0",
+  "pymupdf>=1.24",
+  "python-docx>=1.1",
+  "python-pptx>=0.6.23",
+  "openpyxl>=3.1",
+  "pypdf>=4.0",
+  "jieba>=0.42",
+]
+
+[project.optional-dependencies]
+ocr = ["rapidocr-onnxruntime>=1.3"]
+
+[project.urls]
+Homepage = "https://open.workbuddy.cn"
+
+[project.scripts]
+doc-toolkit-mcp = "doc_toolkit_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/doc_toolkit_mcp"]

doc_toolkit_mcp-0.1.0/src/doc_toolkit_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Local document toolkit MCP server."""
+
+__version__ = "0.1.0"

doc_toolkit_mcp-0.1.0/src/doc_toolkit_mcp/server.py

@@ -0,0 +1,346 @@
+"""Local document toolkit MCP server.
+
+Everything runs on the user's machine — no upload, no API key.
+
+Tools:
+- ``convert_to_markdown``  PDF / DOCX / PPTX / XLSX → Markdown
+- ``ocr_extract``          images and scanned PDFs → text (needs rapidocr-onnxruntime)
+- ``split_chunks``         split a document into retrieval-sized chunks
+- ``pdf_merge``            merge several PDFs
+- ``pdf_split``            split a PDF by page count or page range
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+try:  # mcp SDK v1
+    from mcp.server.fastmcp import FastMCP
+except ImportError:  # mcp SDK v2 renamed FastMCP to MCPServer; decorator API unchanged
+    from mcp.server.mcpserver import MCPServer as FastMCP
+
+mcp = FastMCP("doc-toolkit")
+
+TEXT_EXT = {".md", ".txt", ".csv"}
+
+
+# ── extraction ───────────────────────────────────────────────
+
+def _fmt_table(rows: list[list[str]]) -> str:
+    if not rows:
+        return ""
+    width = max(len(r) for r in rows)
+    rows = [r + [""] * (width - len(r)) for r in rows]
+    lines = ["| " + " | ".join(rows[0]) + " |", "|" + "|".join(["---"] * width) + "|"]
+    lines += ["| " + " | ".join(r) + " |" for r in rows[1:]]
+    return "\n".join(lines)
+
+
+def _from_pdf(path: Path) -> str:
+    import fitz
+
+    parts = []
+    with fitz.open(path) as doc:
+        for i, page in enumerate(doc, 1):
+            text = page.get_text("text").strip()
+            if text:
+                parts.append(f"\n\n<!-- page {i} -->\n\n{text}")
+    return "".join(parts)
+
+
+def _from_docx(path: Path) -> str:
+    from docx import Document
+
+    doc = Document(str(path))
+    out = []
+    for p in doc.paragraphs:
+        t = p.text.strip()
+        if not t:
+            continue
+        style = (p.style.name or "").lower()
+        if style.startswith("heading"):
+            lvl = "".join(ch for ch in style if ch.isdigit()) or "1"
+            out.append("#" * min(int(lvl), 6) + " " + t)
+        elif style.startswith("title"):
+            out.append("# " + t)
+        else:
+            out.append(t)
+    for ti, table in enumerate(doc.tables, 1):
+        rows = [[c.text.strip().replace("\n", " ") for c in r.cells] for r in table.rows]
+        if rows:
+            out.append(f"**表 {ti}**\n\n" + _fmt_table(rows))
+    return "\n\n".join(out)
+
+
+def _from_pptx(path: Path) -> str:
+    from pptx import Presentation
+
+    prs = Presentation(str(path))
+    out = []
+    for i, slide in enumerate(prs.slides, 1):
+        out.append(f"\n## Slide {i}\n")
+        for shape in slide.shapes:
+            if shape.has_text_frame and shape.text_frame.text.strip():
+                out.append(shape.text_frame.text.strip())
+            if getattr(shape, "has_table", False):
+                rows = [[c.text.strip() for c in r.cells] for r in shape.table.rows]
+                if rows:
+                    out.append(_fmt_table(rows))
+    return "\n\n".join(out)
+
+
+def _from_xlsx(path: Path) -> str:
+    from openpyxl import load_workbook
+
+    wb = load_workbook(str(path), read_only=True, data_only=True)
+    out = []
+    for ws in wb.worksheets:
+        out.append(f"\n## {ws.title}\n")
+        rows = []
+        for row in ws.iter_rows(values_only=True):
+            if any(v not in (None, "") for v in row):
+                rows.append([" " if v is None else str(v).strip() for v in row])
+        if rows:
+            out.append(_fmt_table(rows))
+    wb.close()
+    return "\n\n".join(out)
+
+
+def _extract(path: Path) -> str:
+    ext = path.suffix.lower()
+    if ext == ".pdf":
+        return _from_pdf(path)
+    if ext == ".docx":
+        return _from_docx(path)
+    if ext == ".pptx":
+        return _from_pptx(path)
+    if ext in (".xlsx", ".xlsm"):
+        return _from_xlsx(path)
+    if ext in TEXT_EXT:
+        return path.read_text(encoding="utf-8", errors="replace")
+    raise ValueError(f"unsupported format: {ext}")
+
+
+# ── chunking ─────────────────────────────────────────────────
+
+def _token_len(text: str) -> int:
+    try:
+        import logging
+
+        import jieba
+
+        # jieba 首次加载会把 DEBUG 日志打到 stderr，污染 MCP 输出
+        jieba.setLogLevel(logging.WARNING)
+        return len([w for w in jieba.lcut(text) if w.strip()])
+    except Exception:
+        return len(text)
+
+
+def _chunk(md: str, size: int, overlap: int):
+    sections, head, buf = [], "", []
+    for line in md.split("\n"):
+        m = re.match(r"^(#{1,6})\s+(.*)$", line)
+        if m:
+            if buf and "".join(buf).strip():
+                sections.append((head, "\n".join(buf).strip()))
+            head, buf = line.strip(), []
+        else:
+            buf.append(line)
+    if buf and "".join(buf).strip():
+        sections.append((head, "\n".join(buf).strip()))
+
+    chunks = []
+    for heading, body in sections:
+        cur = ""
+        for para in [p.strip() for p in re.split(r"\n\s*\n", body) if p.strip()]:
+            for sent in re.split(r"(?<=[。！？.!?])\s+", para):
+                cand = (cur + " " + sent).strip() if cur else sent
+                if _token_len(cand) > size and cur:
+                    chunks.append({"heading": heading, "text": cur})
+                    words = cur.split()
+                    cur = (" ".join(words[-overlap:]) + " " + sent) if overlap else sent
+                else:
+                    cur = cand
+        if cur.strip():
+            chunks.append({"heading": heading, "text": cur.strip()})
+    return [c for c in chunks if c["text"]]
+
+
+# ── tools ────────────────────────────────────────────────────
+
+@mcp.tool()
+def convert_to_markdown(path: str) -> str:
+    """Convert a local PDF, DOCX, PPTX or XLSX file to Markdown (tables preserved).
+
+    Args:
+        path: Absolute path to the file on the user's machine.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        return f"错误：文件不存在 {p}"
+    try:
+        md = _extract(p)
+    except Exception as exc:
+        return f"错误：转换失败（{exc}）"
+    if not md.strip():
+        return "转换结果为空。如果是扫描版 PDF，请改用 ocr_extract。"
+    return md
+
+
+@mcp.tool()
+def ocr_extract(path: str, dpi: int = 200, max_pages: int = 50) -> str:
+    """OCR an image or scanned PDF into text. Requires the rapidocr-onnxruntime package.
+
+    Pages that already carry a text layer are read directly instead of being OCR'd.
+
+    Args:
+        path: Absolute path to an image or PDF.
+        dpi: Render DPI for PDF pages (200 is a good default, 300 for fuzzy scans).
+        max_pages: Safety cap on how many pages to process.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        return f"错误：文件不存在 {p}"
+    try:
+        from rapidocr_onnxruntime import RapidOCR
+    except ImportError:
+        return "错误：未安装 OCR 依赖。请先执行 pip install rapidocr-onnxruntime"
+
+    engine = RapidOCR()
+    ext = p.suffix.lower()
+
+    if ext == ".pdf":
+        import fitz
+
+        doc = fitz.open(str(p))
+        limit = min(len(doc), max_pages) if max_pages > 0 else len(doc)
+        parts = []
+        for i in range(limit):
+            page = doc[i]
+            text = page.get_text("text").strip()
+            if len(text) > 20:
+                parts.append(f"\n<!-- page {i + 1} · text layer -->\n\n{text}")
+                continue
+            pix = page.get_pixmap(dpi=dpi)
+            tmp = Path(str(p) + f".p{i + 1}.png")
+            pix.save(str(tmp))
+            try:
+                result, _ = engine(str(tmp))
+            finally:
+                tmp.unlink(missing_ok=True)
+            body = "\n".join(line[1] for line in (result or []))
+            parts.append(f"\n<!-- page {i + 1} · ocr -->\n\n{body}")
+        doc.close()
+        out = "".join(parts).strip()
+    else:
+        result, _ = engine(str(p))
+        out = "\n".join(line[1] for line in (result or []))
+
+    return out or "没有识别到文字。"
+
+
+@mcp.tool()
+def split_chunks(path: str, size: int = 800, overlap: int = 100) -> str:
+    """Split a document into retrieval-sized chunks and return them inline.
+
+    Args:
+        path: Absolute path to a document.
+        size: Target tokens per chunk.
+        overlap: Tokens of overlap between consecutive chunks.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        return f"错误：文件不存在 {p}"
+    try:
+        md = p.read_text(encoding="utf-8", errors="replace") if p.suffix.lower() in TEXT_EXT else _extract(p)
+    except Exception as exc:
+        return f"错误：读取失败（{exc}）"
+    chunks = _chunk(md, max(100, size), max(0, overlap))
+    if not chunks:
+        return "没有可切分的内容。"
+    out = [f"共 {len(chunks)} 块："]
+    for i, c in enumerate(chunks, 1):
+        out.append(f"\n--- 块 {i}{' · ' + c['heading'] if c['heading'] else ''} ---\n{c['text']}")
+    return "\n".join(out)
+
+
+@mcp.tool()
+def pdf_merge(inputs: list[str], output: str) -> str:
+    """Merge several PDFs into one, in the order given.
+
+    Args:
+        inputs: Absolute paths of the PDFs to merge.
+        output: Where to write the merged PDF.
+    """
+    from pypdf import PdfReader, PdfWriter
+
+    writer, total = PdfWriter(), 0
+    for item in inputs:
+        p = Path(item).expanduser()
+        if not p.exists():
+            return f"错误：文件不存在 {p}"
+        reader = PdfReader(str(p))
+        for page in reader.pages:
+            writer.add_page(page)
+        total += len(reader.pages)
+    out = Path(output).expanduser()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    with open(out, "wb") as fh:
+        writer.write(fh)
+    return f"已合并 {len(inputs)} 个文件共 {total} 页 → {out}"
+
+
+@mcp.tool()
+def pdf_split(path: str, output_dir: str, every: int = 1, page_range: str = "") -> str:
+    """Split a PDF by page count, or extract a page range.
+
+    Args:
+        path: Absolute path to the PDF.
+        output_dir: Directory to write the parts into.
+        every: When page_range is empty, put this many pages in each output file.
+        page_range: Optional "2-5" or "7" to extract just those pages.
+    """
+    from pypdf import PdfReader, PdfWriter
+
+    src = Path(path).expanduser()
+    if not src.exists():
+        return f"错误：文件不存在 {src}"
+    reader = PdfReader(str(src))
+    n = len(reader.pages)
+    outdir = Path(output_dir).expanduser()
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    if page_range:
+        rng = page_range.replace(" ", "")
+        lo, _, hi = rng.partition("-")
+        lo = int(lo)
+        hi = int(hi) if hi else lo
+        if lo < 1 or hi > n or lo > hi:
+            return f"错误：页码范围不合法（文档共 {n} 页）"
+        w = PdfWriter()
+        for i in range(lo - 1, hi):
+            w.add_page(reader.pages[i])
+        dst = outdir / f"{src.stem}_p{lo}-{hi}.pdf"
+        with open(dst, "wb") as fh:
+            w.write(fh)
+        return f"已提取第 {lo}-{hi} 页 → {dst}"
+
+    step = max(1, every)
+    made = 0
+    for start in range(0, n, step):
+        w = PdfWriter()
+        for i in range(start, min(start + step, n)):
+            w.add_page(reader.pages[i])
+        dst = outdir / f"{src.stem}_p{start + 1}-{min(start + step, n)}.pdf"
+        with open(dst, "wb") as fh:
+            w.write(fh)
+        made += 1
+    return f"已拆成 {made} 个文件 → {outdir}"
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

doc_toolkit_mcp-0.1.0/tests/test_smoke.py

@@ -0,0 +1,45 @@
+"""Smoke tests — no network, no OCR model required."""
+import os
+import tempfile
+
+from doc_toolkit_mcp import server
+
+
+def test_missing_file_is_reported():
+    out = server.convert_to_markdown("definitely-not-here.pdf")
+    assert "文件不存在" in out
+
+
+def test_chunk_respects_headings():
+    md = "## A\n\n第一段内容。\n\n第二段内容。\n\n## B\n\n第三段。"
+    chunks = server._chunk(md, 50, 0)
+    assert any(c["heading"] == "## A" for c in chunks)
+    assert any(c["heading"] == "## B" for c in chunks)
+
+
+def test_table_rendering():
+    out = server._fmt_table([["a", "b"], ["1", "2"]])
+    assert out.splitlines()[0] == "| a | b |"
+    assert "| 1 | 2 |" in out
+
+
+def test_pdf_merge_and_split(tmp_path):
+    import fitz
+
+    paths = []
+    for name, pages in (("a.pdf", 2), ("b.pdf", 1)):
+        doc = fitz.open()
+        for _ in range(pages):
+            doc.new_page()
+        p = tmp_path / name
+        doc.save(str(p))
+        doc.close()
+        paths.append(str(p))
+
+    merged = tmp_path / "merged.pdf"
+    msg = server.pdf_merge(paths, str(merged))
+    assert merged.exists() and "3 页" in msg
+
+    outdir = tmp_path / "parts"
+    msg = server.pdf_split(str(merged), str(outdir), every=2)
+    assert len(list(outdir.glob("*.pdf"))) == 2