precis-mcp 0.2.0__tar.gz

precis_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write  # trusted publishing (OIDC)
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run --no-sync pytest
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

precis_mcp-0.2.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# UV
+uv.lock
+
+# Package-specific
+*.docx.tmp
+*.tex.tmp

precis_mcp-0.2.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to **precis-mcp** will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.0] — 2026-03-11
+
+### Added
+
+- Initial release.

precis_mcp-0.2.0/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 Reto Stamm and Acatome Contributors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.

precis_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: precis-mcp
+Version: 0.2.0
+Summary: MCP server for compressed structured context on .docx and .tex documents
+Project-URL: Homepage, https://github.com/acatome/precis-mcp
+Project-URL: Repository, https://github.com/acatome/precis-mcp
+Project-URL: Issues, https://github.com/acatome/precis-mcp/issues
+Author-email: Reto Stamm <reto@retostamm.com>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: document,docx,keyword-extraction,latex,llm,mcp,precis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup
+Requires-Python: >=3.11
+Requires-Dist: lxml>=5.0
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: precis-summary>=0.1.0
+Requires-Dist: python-docx>=1.1
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# precis-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives LLMs compressed, structured context for `.docx` and `.tex` documents. It maintains a heading tree with RAKE keyword summaries so the LLM can navigate and edit documents without flooding context.
+
+## Features
+
+- **5 tools** — `activate`, `toc`, `get`, `put`, `move`
+- **Dual addressing** — 5-char content-hash slugs + positional heading paths
+- **RAKE keyword extraction** — stateless, zero-dependency precis generation (<5ms)
+- **DOCX citations** — `[@key]` round-trip with styled hyperlinks and bibliography entries
+- **Track changes** — `put()` writes Word revision markup by default
+- **LaTeX support** — `\input`/`\include` resolution, `\label{}` aliases, `.bib` parsing
+- **Atomic I/O** — every call reads fresh from disk, no stale state
+
+## Installation
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+Run as an MCP server:
+
+```bash
+precis
+```
+
+Or use with an MCP client:
+
+```python
+from precis.tools import Session, activate, toc, get, put
+
+session = Session()
+await activate(session, "paper.docx")
+await toc(session)
+await get(session, id="KR8M2")
+await put(session, id="KR8M2", text="Updated text.", mode="replace")
+```
+
+## Configuration
+
+`~/.config/precis/precis.toml`:
+
+```toml
+[precis]
+author = "precis"   # track-changes author name (DOCX only)
+```
+
+## Testing
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).

precis_mcp-0.2.0/README.md

@@ -0,0 +1,58 @@
+# precis-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives LLMs compressed, structured context for `.docx` and `.tex` documents. It maintains a heading tree with RAKE keyword summaries so the LLM can navigate and edit documents without flooding context.
+
+## Features
+
+- **5 tools** — `activate`, `toc`, `get`, `put`, `move`
+- **Dual addressing** — 5-char content-hash slugs + positional heading paths
+- **RAKE keyword extraction** — stateless, zero-dependency precis generation (<5ms)
+- **DOCX citations** — `[@key]` round-trip with styled hyperlinks and bibliography entries
+- **Track changes** — `put()` writes Word revision markup by default
+- **LaTeX support** — `\input`/`\include` resolution, `\label{}` aliases, `.bib` parsing
+- **Atomic I/O** — every call reads fresh from disk, no stale state
+
+## Installation
+
+```bash
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+Run as an MCP server:
+
+```bash
+precis
+```
+
+Or use with an MCP client:
+
+```python
+from precis.tools import Session, activate, toc, get, put
+
+session = Session()
+await activate(session, "paper.docx")
+await toc(session)
+await get(session, id="KR8M2")
+await put(session, id="KR8M2", text="Updated text.", mode="replace")
+```
+
+## Configuration
+
+`~/.config/precis/precis.toml`:
+
+```toml
+[precis]
+author = "precis"   # track-changes author name (DOCX only)
+```
+
+## Testing
+
+```bash
+uv run python -m pytest tests/ -v
+```
+
+## License
+
+GPL-3.0-or-later — see [LICENSE](LICENSE).

precis_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "precis-mcp"
+version = "0.2.0"
+description = "MCP server for compressed structured context on .docx and .tex documents"
+requires-python = ">=3.11"
+license = "GPL-3.0-or-later"
+authors = [{name = "Reto Stamm", email = "reto@retostamm.com"}]
+readme = "README.md"
+keywords = ["mcp", "docx", "latex", "llm", "document", "precis", "keyword-extraction"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Text Processing :: Markup",
+]
+
+dependencies = [
+    "mcp[cli]>=1.0",
+    "python-docx>=1.1",
+    "lxml>=5.0",
+    "platformdirs>=4.0",
+    "precis-summary>=0.1.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/acatome/precis-mcp"
+Repository = "https://github.com/acatome/precis-mcp"
+Issues = "https://github.com/acatome/precis-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "black>=24.0",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+precis = "precis.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/precis"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.black]
+line-length = 88
+
+[tool.ruff]
+line-length = 88
+
+[tool.bumpversion]
+current_version = "0.2.0"
+commit = true
+tag = true
+tag_name = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = 'version = "{current_version}"'
+replace = 'version = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "src/precis/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

precis_mcp-0.2.0/src/precis/__init__.py

@@ -0,0 +1,3 @@
+"""Precis MCP — compressed structured context for .docx and .tex documents."""
+
+__version__ = "0.2.0"

precis_mcp-0.2.0/src/precis/citations.py

@@ -0,0 +1,176 @@
+"""Citation system — style engine, bookmark/link helpers, DOCX style creation."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Markdown citation patterns
+# ---------------------------------------------------------------------------
+
+# Inline citation: [@key]
+CITE_RE = re.compile(r"\[@([^\]\s]+)\]")
+
+# Orphaned citation (lost bookmark, style survived): [@?:displayed text]
+ORPHAN_CITE_RE = re.compile(r"\[@\?:([^\]]+)\]")
+
+# Bibliography definition: [@key]: full reference text
+BIB_DEF_RE = re.compile(r"^\[@([^\]\s]+)\]:\s*(.+)$")
+
+ORPHAN_PREFIX = "?:"
+
+
+def is_orphan_key(key: str) -> bool:
+    """True if the key is an orphaned citation (lost bookmark, style survived)."""
+    return key.startswith(ORPHAN_PREFIX)
+
+
+def orphan_text(key: str) -> str:
+    """Extract the displayed text from an orphan key."""
+    return key[len(ORPHAN_PREFIX) :]
+
+
+# ---------------------------------------------------------------------------
+# Bookmark naming (for bibliography definitions only)
+# ---------------------------------------------------------------------------
+
+REF_BOOKMARK_RE = re.compile(r"^ref_(.+)$")
+
+
+def ref_bookmark_name(key: str) -> str:
+    """Generate bookmark name for a bibliography entry."""
+    return f"ref_{key}"
+
+
+def parse_ref_bookmark(name: str) -> str | None:
+    """Parse ref_key → key or None."""
+    m = REF_BOOKMARK_RE.match(name)
+    if m:
+        return m.group(1)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Citation styles
+# ---------------------------------------------------------------------------
+
+STYLES = ("author-year", "numbered", "superscript")
+
+
+@dataclass
+class BibEntry:
+    """A bibliography entry with parsed metadata for rendering."""
+
+    key: str
+    text: str  # full formatted reference
+    author_short: str = ""  # "Smith" or "Smith & Jones" or "Smith et al."
+    year: str = ""
+
+    def render_author_year(self) -> str:
+        if self.author_short and self.year:
+            return f"({self.author_short} {self.year})"
+        return f"[@{self.key}]"
+
+
+@dataclass
+class CitationIndex:
+    """Tracks citation order and bibliography for a document."""
+
+    style: str = "author-year"
+    entries: dict[str, BibEntry] = field(default_factory=dict)
+    cite_order: list[str] = field(default_factory=list)
+
+    def register_bib(self, key: str, text: str) -> None:
+        """Register a bibliography entry."""
+        author_short, year = _parse_author_year(text)
+        self.entries[key] = BibEntry(
+            key=key, text=text, author_short=author_short, year=year
+        )
+
+    def cite(self, key: str) -> int:
+        """Record a citation occurrence. Returns the 1-based citation number."""
+        if key not in self.cite_order:
+            self.cite_order.append(key)
+        return self.cite_order.index(key) + 1
+
+    def render_inline(self, key: str) -> tuple[str, bool]:
+        """Render an inline citation. Returns (text, is_superscript)."""
+        num = self.cite(key)
+        if self.style == "numbered":
+            return f"[{num}]", False
+        elif self.style == "superscript":
+            return str(num), True
+        else:  # author-year
+            entry = self.entries.get(key)
+            if entry:
+                return entry.render_author_year(), False
+            return f"[@{key}]", False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "style": self.style,
+            "entries": {
+                k: {"text": e.text, "author_short": e.author_short, "year": e.year}
+                for k, e in self.entries.items()
+            },
+            "cite_order": self.cite_order,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CitationIndex:
+        idx = cls(style=data.get("style", "author-year"))
+        idx.cite_order = data.get("cite_order", [])
+        for k, v in data.get("entries", {}).items():
+            idx.entries[k] = BibEntry(
+                key=k,
+                text=v.get("text", ""),
+                author_short=v.get("author_short", ""),
+                year=v.get("year", ""),
+            )
+        return idx
+
+
+# ---------------------------------------------------------------------------
+# Author/year extraction heuristic
+# ---------------------------------------------------------------------------
+
+# Matches "(2020)" or ", 2020" or "(2020)." at the end-ish of a reference
+_YEAR_RE = re.compile(r"\b((?:19|20)\d{2})\b")
+# First word(s) before a comma — typically the author surname
+_AUTHOR_RE = re.compile(r"^([A-Z][a-z]+(?:\s*(?:&|and)\s*[A-Z][a-z]+)?)")
+
+
+def _parse_author_year(text: str) -> tuple[str, str]:
+    """Best-effort extraction of (author_short, year) from a reference string.
+
+    Returns ("", "") if nothing found.
+    """
+    year = ""
+    author = ""
+
+    ym = _YEAR_RE.search(text)
+    if ym:
+        year = ym.group(1)
+
+    am = _AUTHOR_RE.match(text.strip())
+    if am:
+        author = am.group(1)
+        # Check for et al. — if there's more text after the matched authors
+        # before the year, assume et al.
+        rest = text.strip()[am.end() :].lstrip(",").strip()
+        if rest and not rest[0].isdigit() and "&" not in am.group(1):
+            # More authors follow — use et al.
+            if "," in rest.split("(")[0] if "(" in rest else rest:
+                author = f"{author} et al."
+
+    return author, year
+
+
+# ---------------------------------------------------------------------------
+# DOCX style names
+# ---------------------------------------------------------------------------
+
+CITATION_REF_STYLE = "CitationRef"
+BIB_ENTRY_STYLE = "BibEntry"

precis_mcp-0.2.0/src/precis/config.py

@@ -0,0 +1,39 @@
+"""Configuration from ~/.config/precis/precis.toml."""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".config" / "precis"
+DEFAULT_CONFIG_FILE = DEFAULT_CONFIG_DIR / "precis.toml"
+
+
+@dataclass
+class PrecisConfig:
+    """Precis config — just track-changes author name."""
+
+    author: str = "precis"
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> PrecisConfig:
+        """Load config from TOML file, falling back to defaults."""
+        path = path or DEFAULT_CONFIG_FILE
+        if not path.exists():
+            return cls()
+        try:
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+            section = data.get("precis", {})
+            return cls(
+                author=section.get("author", cls.author),
+            )
+        except Exception:
+            return cls()

precis_mcp-0.2.0/src/precis/formatting.py

@@ -0,0 +1,114 @@
+"""Markdown ↔ DOCX run formatting conversion."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class FormattedRun:
+    """A text run with formatting properties."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    superscript: bool = False
+    subscript: bool = False
+    strike: bool = False
+    url: str = ""  # non-empty = hyperlink
+    cite_key: str = ""  # non-empty = citation reference [@key]
+
+
+def runs_to_markdown(runs: list[FormattedRun]) -> str:
+    """Convert formatted runs to Markdown text."""
+    parts = []
+    for r in runs:
+        t = r.text
+        if r.cite_key:
+            t = f"[@{r.cite_key}]"
+        elif r.url:
+            t = f"[{t}]({r.url})"
+        if r.superscript:
+            t = f"<sup>{t}</sup>"
+        if r.subscript:
+            t = f"<sub>{t}</sub>"
+        if r.bold and r.italic:
+            t = f"***{t}***"
+        elif r.bold:
+            t = f"**{t}**"
+        elif r.italic:
+            t = f"*{t}*"
+        if r.strike:
+            t = f"~~{t}~~"
+        parts.append(t)
+    return "".join(parts)
+
+
+# Patterns for parsing Markdown back to runs
+_PATTERNS = [
+    # Bold+italic
+    (re.compile(r"\*\*\*(.+?)\*\*\*"), {"bold": True, "italic": True}),
+    # Bold
+    (re.compile(r"\*\*(.+?)\*\*"), {"bold": True}),
+    # Italic
+    (re.compile(r"\*(.+?)\*"), {"italic": True}),
+    # Strikethrough
+    (re.compile(r"~~(.+?)~~"), {"strike": True}),
+    # Superscript
+    (re.compile(r"<sup>(.+?)</sup>"), {"superscript": True}),
+    # Subscript
+    (re.compile(r"<sub>(.+?)</sub>"), {"subscript": True}),
+    # Hyperlink
+    (re.compile(r"\[(.+?)\]\((.+?)\)"), {"url": True}),
+    # Citation: [@key]
+    (re.compile(r"\[@([^\]\s]+)\]"), {"cite_key": True}),
+]
+
+
+def markdown_to_runs(text: str) -> list[FormattedRun]:
+    """Parse Markdown text into FormattedRun objects.
+
+    Handles bold, italic, superscript, subscript, strikethrough, and hyperlinks.
+    Unrecognized text becomes plain runs.
+    """
+    if not text:
+        return []
+
+    # Use a token-based approach: find all formatting spans, sort by position
+    spans: list[tuple[int, int, FormattedRun]] = []
+
+    for pattern, props in _PATTERNS:
+        for m in pattern.finditer(text):
+            if "url" in props:
+                run = FormattedRun(text=m.group(1), url=m.group(2))
+            elif "cite_key" in props:
+                key = m.group(1)
+                run = FormattedRun(text=f"[@{key}]", cite_key=key)
+            else:
+                run = FormattedRun(text=m.group(1), **props)
+            spans.append((m.start(), m.end(), run))
+
+    if not spans:
+        return [FormattedRun(text=text)]
+
+    # Sort by start position, resolve overlaps (first match wins)
+    spans.sort(key=lambda s: s[0])
+    result: list[FormattedRun] = []
+    pos = 0
+
+    for start, end, run in spans:
+        if start < pos:
+            continue  # overlapping span, skip
+        if start > pos:
+            plain = text[pos:start]
+            if plain:
+                result.append(FormattedRun(text=plain))
+        result.append(run)
+        pos = end
+
+    # Trailing plain text
+    if pos < len(text):
+        result.append(FormattedRun(text=text[pos:]))
+
+    return result