pullini-mcp 0.7.1__py3-none-any.whl

pullini_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""pullini-mcp: a local stdio MCP connector for Pullini artifacts (E6, T6)."""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.7.1"

pullini_mcp/client.py

@@ -0,0 +1,167 @@
+"""Thin HTTP client over the Pullini artifact REST API (E6, T6).
+
+The connector runs on the agent's machine and talks to the Pullini host with a
+personal access token sent as a bearer header (D-25). This module owns all HTTP
+concerns so :mod:`pullini_mcp.server` only maps MCP tool calls to methods and
+turns :class:`PulliniError` into a readable tool failure.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class PulliniError(Exception):
+    """A readable error for a transport failure or a non-2xx API response."""
+
+
+@dataclass(frozen=True)
+class Config:
+    """Connection settings read from the environment (``PULLINI_URL``/``PULLINI_TOKEN``)."""
+
+    base_url: str
+    token: str
+    timeout: float = DEFAULT_TIMEOUT
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> Config:
+        """Build a config from ``PULLINI_URL`` and ``PULLINI_TOKEN``."""
+        source = os.environ if env is None else env
+        base_url = (source.get("PULLINI_URL") or "").strip().rstrip("/")
+        token = (source.get("PULLINI_TOKEN") or "").strip()
+        if not base_url:
+            raise PulliniError(
+                "PULLINI_URL is not set. Point it at your Pullini host, e.g. "
+                "https://pullini.example.com."
+            )
+        if not token:
+            raise PulliniError(
+                "PULLINI_TOKEN is not set. Create a token at /settings/tokens/ and "
+                "pass the raw secret."
+            )
+        return cls(base_url=base_url, token=token)
+
+
+class PulliniClient:
+    """Minimal client for the endpoints that back the artifact API."""
+
+    def __init__(self, config: Config, *, transport: httpx.BaseTransport | None = None) -> None:
+        self._config = config
+        self._client = httpx.Client(
+            base_url=config.base_url,
+            headers={
+                "Authorization": f"Bearer {config.token}",
+                "Accept": "application/json",
+            },
+            timeout=config.timeout,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> PulliniClient:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()
+
+    # --- transport -----------------------------------------------------------
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, json=json, headers=headers)
+        except httpx.HTTPError as exc:
+            raise PulliniError(
+                f"Could not reach Pullini at {self._config.base_url}: {exc}"
+            ) from exc
+        if response.status_code >= 400:
+            raise self._error(response)
+        return response
+
+    def _request(self, method: str, path: str, *, json: dict | None = None) -> Any:
+        response = self._send(method, path, json=json)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def _error(self, response: httpx.Response) -> PulliniError:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {}
+        code = payload.get("error")
+        detail = payload.get("detail") or response.reason_phrase or "Request failed."
+        message = (
+            f"{response.status_code} {code}: {detail}"
+            if code
+            else f"{response.status_code}: {detail}"
+        )
+        if response.status_code == 401:
+            message += " Check that PULLINI_TOKEN is valid and not expired or revoked."
+        if response.status_code == 404:
+            message += " The artifact may not exist or may belong to another user."
+        return PulliniError(message)
+
+    # --- endpoints -----------------------------------------------------------
+
+    def me(self) -> dict:
+        """Return the token owner and token metadata (``GET /api/me/``)."""
+        return self._request("GET", "/api/me/")
+
+    def skill(self) -> str:
+        """Return the agent skill Markdown (``GET /api/skill/``)."""
+        return self._send("GET", "/api/skill/", headers={"Accept": "text/markdown"}).text
+
+    def list_artifacts(self) -> list[dict]:
+        """Return the token owner's artifacts (``GET /api/artifacts/``)."""
+        payload = self._request("GET", "/api/artifacts/")
+        return payload.get("artifacts", [])
+
+    def get_artifact(self, slug: str) -> dict:
+        """Return one artifact with source Markdown and rendered HTML."""
+        return self._request("GET", f"/api/artifacts/{quote(slug)}/")
+
+    def create_artifact(self, title: str, content: str, visibility: str = "private") -> dict:
+        """Create an artifact (``POST /api/artifacts/``)."""
+        return self._request(
+            "POST",
+            "/api/artifacts/",
+            json={"title": title, "content": content, "visibility": visibility},
+        )
+
+    def update_artifact(
+        self, slug: str, *, title: str | None = None, content: str | None = None
+    ) -> dict:
+        """Partially update an artifact (``PATCH /api/artifacts/<slug>/``)."""
+        if title is None and content is None:
+            raise PulliniError("Provide a new title and/or content to update.")
+        body: dict[str, str] = {}
+        if title is not None:
+            body["title"] = title
+        if content is not None:
+            body["content"] = content
+        return self._request("PATCH", f"/api/artifacts/{quote(slug)}/", json=body)
+
+    def delete_artifact(self, slug: str) -> None:
+        """Delete an artifact (``DELETE /api/artifacts/<slug>/``)."""
+        self._request("DELETE", f"/api/artifacts/{quote(slug)}/")
+
+    def share_artifact(self, slug: str, *, enable: bool = True) -> dict | None:
+        """Enable or revoke the unlisted share link (``POST``/``DELETE .../share/``)."""
+        method = "POST" if enable else "DELETE"
+        return self._request(method, f"/api/artifacts/{quote(slug)}/share/")

pullini_mcp/server.py

@@ -0,0 +1,141 @@
+"""MCP stdio server exposing Pullini artifacts as MCP tools (E6, T6).
+
+Every tool is a thin translation of an MCP call into a
+:class:`~pullini_mcp.client.PulliniClient` request. Configuration comes from the
+environment (``PULLINI_URL``/``PULLINI_TOKEN``, D-25), so the server holds no
+state between calls and needs no ASGI/OAuth infrastructure on the Pullini host.
+
+In ``mcp`` 2.x the server class formerly named ``FastMCP`` is ``MCPServer``.
+"""
+
+from __future__ import annotations
+
+from importlib.resources import files
+
+from mcp.server.mcpserver import MCPServer
+
+from pullini_mcp import __version__
+from pullini_mcp.client import Config, PulliniClient, PulliniError
+
+mcp = MCPServer("pullini", version=__version__)
+
+_VISIBILITIES = ("private", "unlisted")
+
+
+def _client() -> PulliniClient:
+    return PulliniClient(Config.from_env())
+
+
+def _check_visibility(visibility: str) -> str:
+    if visibility not in _VISIBILITIES:
+        raise PulliniError('"visibility" must be "private" or "unlisted".')
+    return visibility
+
+
+@mcp.tool()
+def store_artifact(
+    title: str,
+    content: str,
+    visibility: str = "private",
+    slug: str | None = None,
+) -> dict:
+    """Create an artifact, or overwrite the artifact identified by ``slug``.
+
+    Args:
+        title: Short human-readable title.
+        content: Markdown source; fenced ``mermaid`` blocks render as diagrams.
+        visibility: ``"private"`` (default) or ``"unlisted"`` (active share link).
+        slug: When given, overwrite that artifact instead of creating a new one.
+    """
+    _check_visibility(visibility)
+    client = _client()
+    try:
+        if slug:
+            artifact = client.update_artifact(slug, title=title, content=content)
+            if visibility == "unlisted" and not artifact.get("share_url"):
+                artifact = client.share_artifact(slug) or artifact
+            elif visibility == "private" and artifact.get("share_url"):
+                client.share_artifact(slug, enable=False)
+                artifact = client.get_artifact(slug)
+            return artifact
+        return client.create_artifact(title, content, visibility)
+    finally:
+        client.close()
+
+
+@mcp.tool()
+def list_artifacts() -> list[dict]:
+    """List the artifacts owned by the configured token."""
+    client = _client()
+    try:
+        return client.list_artifacts()
+    finally:
+        client.close()
+
+
+@mcp.tool()
+def get_artifact(slug: str) -> dict:
+    """Fetch one artifact: source Markdown, rendered HTML and plain text."""
+    client = _client()
+    try:
+        return client.get_artifact(slug)
+    finally:
+        client.close()
+
+
+@mcp.tool()
+def update_artifact(slug: str, title: str | None = None, content: str | None = None) -> dict:
+    """Change an artifact's title and/or content. The slug never changes."""
+    client = _client()
+    try:
+        return client.update_artifact(slug, title=title, content=content)
+    finally:
+        client.close()
+
+
+@mcp.tool()
+def delete_artifact(slug: str) -> dict:
+    """Delete an artifact by slug."""
+    client = _client()
+    try:
+        client.delete_artifact(slug)
+        return {"slug": slug, "deleted": True}
+    finally:
+        client.close()
+
+
+@mcp.tool()
+def share_artifact(slug: str, enable: bool = True) -> dict:
+    """Enable (``enable=True``) or revoke (``enable=False``) the unlisted share link.
+
+    Enabling returns the artifact with a ``share_url``; revoking clears it.
+    """
+    client = _client()
+    try:
+        if enable:
+            return client.share_artifact(slug) or {}
+        client.share_artifact(slug, enable=False)
+        return {"slug": slug, "share_url": None}
+    finally:
+        client.close()
+
+
+@mcp.resource(
+    "pullini://skill",
+    name="pullini-skill",
+    title="Pullini artifacts skill",
+    description="Agent skill describing how to use the Pullini MCP artifact tools.",
+    mime_type="text/markdown",
+)
+def skill() -> str:
+    """Return the local agent skill describing the MCP tools."""
+    return files("pullini_mcp").joinpath("skill.md").read_text(encoding="utf-8")
+
+
+def main() -> None:
+    """Run the stdio server (entry point for ``uvx pullini-mcp``)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pullini_mcp/skill.md

@@ -0,0 +1,34 @@
+---
+name: pullini-artifacts
+description: Use the Pullini MCP tools to create, read, update, delete and share user-owned Markdown artifacts (notes, reports, Mermaid diagrams) on a Pullini host. Use when persisting AI-generated documents.
+---
+
+# Pullini artifacts (MCP)
+
+Artifacts are user-owned Markdown documents (tables, code and `mermaid` diagrams
+render). They are **private by default**. Use the tools below; the connector
+handles the host URL and token for you — never ask the user for either.
+
+## Tools
+
+- `store_artifact(title, content, visibility="private", slug=None)` — create, or
+  overwrite when `slug` is given.
+- `list_artifacts()` — the artifacts you own.
+- `get_artifact(slug)` — source Markdown, rendered HTML and plain text.
+- `update_artifact(slug, title=None, content=None)` — change the title and/or content.
+- `delete_artifact(slug)` — delete one.
+- `share_artifact(slug, enable=True)` — enable/revoke the unlisted `share_url`.
+
+## Workflow
+
+1. Create with `store_artifact`; note the returned `slug` — it is **frozen**, so
+   later edits use the slug, not the title (renaming keeps the slug).
+2. Edit with `update_artifact(slug, ...)`.
+3. Share with `share_artifact`; anyone holding the `share_url` can read it.
+
+## Authoring
+
+- `content` is Markdown; fenced ` ```mermaid ` blocks render as diagrams. Raw
+  HTML is sanitized.
+- Keep `title` short; put structure in the Markdown headings.
+- `visibility` is `"private"` (default) or `"unlisted"`.

pullini_mcp-0.7.1.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.5
+Name: pullini-mcp
+Version: 0.7.1
+Summary: Local stdio MCP connector for Pullini artifacts (E6, T6).
+Project-URL: Homepage, https://github.com/rykhalskyi/pullini
+Project-URL: Repository, https://github.com/rykhalskyi/pullini
+Project-URL: Issues, https://github.com/rykhalskyi/pullini/issues
+Author-email: Iaroslav Rykhalskyi <rikhalskiy@gmail.com>
+License-Expression: MIT
+Keywords: agents,artifacts,fastmcp,mcp,pullini
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=2
+Description-Content-Type: text/markdown
+
+# pullini-mcp
+
+A local **stdio** [MCP](https://modelcontextprotocol.io) connector that lets an
+agent create, read, update, delete and share [Pullini](https://github.com/rykhalskyi/pullini)
+artifacts over the authenticated artifact REST API.
+
+The connector runs on the agent's machine. It reads its configuration from the
+environment and needs no ASGI or OAuth infrastructure on the Pullini host
+(decision D-25).
+
+## Install
+
+Runs with [uv](https://docs.astral.sh/uv/), no install step required:
+
+```bash
+uvx pullini-mcp
+```
+
+Or install it into an environment:
+
+```bash
+uv tool install pullini-mcp   # or: pip install pullini-mcp
+```
+
+## Configure
+
+Two environment variables:
+
+| Variable        | Description                                                        |
+| --------------- | ------------------------------------------------------------------ |
+| `PULLINI_URL`   | Base URL of your Pullini host, e.g. `https://pullini.example.com`. |
+| `PULLINI_TOKEN` | A personal access token created at `/settings/tokens/` (`pln_…`).  |
+
+The token is sent as `Authorization: Bearer <token>`; all resources are scoped to
+the token's owner. Treat the raw secret like a password.
+
+### MCP client config
+
+The client launches the server and passes the two variables. A copy-paste
+example lives in [`mcp.example.json`](mcp.example.json).
+
+**From a local checkout** (before the package is published): point `--directory`
+at the `mcp/` folder of your clone.
+
+```json
+{
+  "mcpServers": {
+    "pullini": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/pullini/mcp", "pullini-mcp"],
+      "env": {
+        "PULLINI_URL": "http://localhost:8000",
+        "PULLINI_TOKEN": "pln_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy"
+      }
+    }
+  }
+}
+```
+
+**From PyPI** (once published):
+
+```json
+{
+  "mcpServers": {
+    "pullini": {
+      "command": "uvx",
+      "args": ["pullini-mcp"],
+      "env": {
+        "PULLINI_URL": "https://pullini.example.com",
+        "PULLINI_TOKEN": "pln_xxxxxxxx_yyyyyyyyyyyyyyyyyyyyyyyy"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool              | What it does                                                   |
+| ----------------- | -------------------------------------------------------------- |
+| `store_artifact`  | Create an artifact, or overwrite one when `slug` is given.     |
+| `list_artifacts`  | List the token owner's artifacts.                              |
+| `get_artifact`    | Fetch one artifact (source Markdown, rendered HTML, plain text). |
+| `update_artifact` | Change an artifact's title and/or content.                     |
+| `delete_artifact` | Delete an artifact.                                            |
+| `share_artifact`  | Enable or revoke the unlisted share link.                      |
+
+`content` is Markdown; fenced ` ```mermaid ` blocks render as diagrams. Artifacts
+are **private by default**: `share_artifact` returns a read-only `share_url`
+anyone with the link can open, and revoking clears it.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+Tests mock the HTTP transport with `httpx.MockTransport`, so no Pullini host is
+needed.

pullini_mcp-0.7.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+pullini_mcp/__init__.py,sha256=hnd1o_fbxCeU82UcrL4N-SMen4KBAT5Ibn5rb2ymfOM,165
+pullini_mcp/client.py,sha256=LtGM6H9WA-aGNuTCKF1OgksxvNXtU8h3uPzUaT5spYs,6211
+pullini_mcp/server.py,sha256=yFqRqpiks3bITvbtmrBfXuJzdVtYL2NXBjU7_talcZ4,4211
+pullini_mcp/skill.md,sha256=joP2Yeb6LwXtCyj3bH73lK4vNsMsVUz3WEUcXnXpGeo,1483
+pullini_mcp-0.7.1.dist-info/METADATA,sha256=jIXcvVZkAefNC9XfPL6zy_T8K35bQpk9WVtFf2GFzME,4188
+pullini_mcp-0.7.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pullini_mcp-0.7.1.dist-info/entry_points.txt,sha256=QndFgDk1j2WnF0H8YGebNfRAIfrgHXqas9xzFtZxfq8,56
+pullini_mcp-0.7.1.dist-info/RECORD,,

pullini_mcp-0.7.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pullini_mcp-0.7.1.dist-info/entry_points.txt

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