mataroa-mcp 0.1.0__tar.gz

mataroa_mcp-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+*.pyc
+__pycache__/
+*.egg-info/
+.pytest_cache/

mataroa_mcp-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

mataroa_mcp-0.1.0/LICENSE

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

mataroa_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: mataroa-mcp
+Version: 0.1.0
+Summary: MCP server for managing a Mataroa blog via natural language
+License: MIT License
+        
+        Copyright (c) 2026 Ayush
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# mataroa-mcp
+
+An MCP server that lets you manage your [Mataroa](https://mataroa.blog) blog through natural language in Claude Desktop, Claude Code, or any MCP-compatible AI client.
+
+---
+
+## What you can do
+
+Tell Claude things like:
+
+- *"Show me all my blog posts"*
+- *"Write a post about my weekend hike and save it as a draft"*
+- *"Publish my sourdough post"*
+- *"Are there any comments waiting for approval?"*
+- *"Delete the draft called testing-123"*
+- *"Create an About page for my blog"*
+
+Claude will call the right tool automatically.
+
+---
+
+## Setup (5 minutes)
+
+### 1. Get your Mataroa API key
+
+1. Go to [mataroa.blog](https://mataroa.blog) and log in (or create a free account).
+2. Open **Dashboard → API** and copy your API key.
+
+### 2. Install the server
+
+You need Python 3.10 or later. Clone this repo and install it locally:
+
+```bash
+git clone https://github.com/ayush111111/matoroa-mcp.git
+cd matoroa-mcp
+pip install -e .
+```
+
+### 3. Add to Claude Desktop
+
+Open your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+If there is no `"mcpServers"` key, add it at the top level alongside any existing keys:
+
+```json
+{
+  "mcpServers": {
+    "mataroa": {
+      "command": "python",
+      "args": ["-m", "mataroa_mcp.server"],
+      "env": {
+        "MATAROA_API_KEY": "paste-your-key-here"
+      }
+    }
+  },
+  "...your other existing config keys...": "..."
+}
+```
+
+> **Note:** Once `mataroa-mcp` is published to PyPI you can replace `"command": "python", "args": ["-m", "mataroa_mcp.server"]` with `"command": "uvx", "args": ["mataroa-mcp"]` and skip the clone/install step entirely.
+
+### 4. Restart Claude Desktop
+
+Quit and reopen Claude Desktop. You should see a small plug icon in the chat bar indicating MCP tools are active.
+
+### 5. Test it
+
+Type: *"Show me my blog posts"* — Claude should list them.
+
+---
+
+## Add to Claude Code
+
+Create or edit `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mataroa": {
+      "command": "python",
+      "args": ["-m", "mataroa_mcp.server"],
+      "env": {
+        "MATAROA_API_KEY": "paste-your-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available tools
+
+| Tool | What it does |
+|------|-------------|
+| `list_posts` | List all posts (published + drafts) |
+| `list_drafts` | List only unpublished drafts |
+| `get_post` | Get a single post by slug |
+| `create_post` | Create a new post |
+| `update_post` | Edit an existing post |
+| `delete_post` | Permanently delete a post |
+| `publish_post` | Publish a draft (sets today's date, or a date you choose) |
+| `unpublish_post` | Revert a published post back to draft |
+| `list_comments` | List all comments (or just for one post) |
+| `list_pending_comments` | List comments awaiting moderation |
+| `approve_comment` | Approve a pending comment |
+| `delete_comment` | Delete a comment |
+| `list_pages` | List all pages |
+| `get_page` | Get a single page by slug |
+| `create_page` | Create a new page |
+| `update_page` | Edit an existing page |
+| `delete_page` | Permanently delete a page |
+
+---
+
+## Notes
+
+- **API key is never stored in code** — it's always read from the `MATAROA_API_KEY` environment variable.
+- **Mataroa has no rate limiting**, so you can make requests freely.
+- **Blog-level settings** (title, custom domain, etc.) are not accessible via the Mataroa API and therefore not exposed here.
+- Draft posts have `published_at: null`. Publishing sets it to a date; unpublishing clears it.
+
+---
+
+## Running tests
+
+```bash
+# Unit tests (no API key needed)
+pip install -e .
+pip install pytest pytest-asyncio respx
+pytest tests/test_client.py tests/test_server.py -v
+
+# Integration tests (requires a real Mataroa API key)
+MATAROA_API_KEY=your-key pytest tests/test_integration.py --run-integration -v
+```
+
+---
+
+## License
+
+MIT

mataroa_mcp-0.1.0/README.md

@@ -0,0 +1,144 @@
+# mataroa-mcp
+
+An MCP server that lets you manage your [Mataroa](https://mataroa.blog) blog through natural language in Claude Desktop, Claude Code, or any MCP-compatible AI client.
+
+---
+
+## What you can do
+
+Tell Claude things like:
+
+- *"Show me all my blog posts"*
+- *"Write a post about my weekend hike and save it as a draft"*
+- *"Publish my sourdough post"*
+- *"Are there any comments waiting for approval?"*
+- *"Delete the draft called testing-123"*
+- *"Create an About page for my blog"*
+
+Claude will call the right tool automatically.
+
+---
+
+## Setup (5 minutes)
+
+### 1. Get your Mataroa API key
+
+1. Go to [mataroa.blog](https://mataroa.blog) and log in (or create a free account).
+2. Open **Dashboard → API** and copy your API key.
+
+### 2. Install the server
+
+You need Python 3.10 or later. Clone this repo and install it locally:
+
+```bash
+git clone https://github.com/ayush111111/matoroa-mcp.git
+cd matoroa-mcp
+pip install -e .
+```
+
+### 3. Add to Claude Desktop
+
+Open your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+If there is no `"mcpServers"` key, add it at the top level alongside any existing keys:
+
+```json
+{
+  "mcpServers": {
+    "mataroa": {
+      "command": "python",
+      "args": ["-m", "mataroa_mcp.server"],
+      "env": {
+        "MATAROA_API_KEY": "paste-your-key-here"
+      }
+    }
+  },
+  "...your other existing config keys...": "..."
+}
+```
+
+> **Note:** Once `mataroa-mcp` is published to PyPI you can replace `"command": "python", "args": ["-m", "mataroa_mcp.server"]` with `"command": "uvx", "args": ["mataroa-mcp"]` and skip the clone/install step entirely.
+
+### 4. Restart Claude Desktop
+
+Quit and reopen Claude Desktop. You should see a small plug icon in the chat bar indicating MCP tools are active.
+
+### 5. Test it
+
+Type: *"Show me my blog posts"* — Claude should list them.
+
+---
+
+## Add to Claude Code
+
+Create or edit `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mataroa": {
+      "command": "python",
+      "args": ["-m", "mataroa_mcp.server"],
+      "env": {
+        "MATAROA_API_KEY": "paste-your-key-here"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Available tools
+
+| Tool | What it does |
+|------|-------------|
+| `list_posts` | List all posts (published + drafts) |
+| `list_drafts` | List only unpublished drafts |
+| `get_post` | Get a single post by slug |
+| `create_post` | Create a new post |
+| `update_post` | Edit an existing post |
+| `delete_post` | Permanently delete a post |
+| `publish_post` | Publish a draft (sets today's date, or a date you choose) |
+| `unpublish_post` | Revert a published post back to draft |
+| `list_comments` | List all comments (or just for one post) |
+| `list_pending_comments` | List comments awaiting moderation |
+| `approve_comment` | Approve a pending comment |
+| `delete_comment` | Delete a comment |
+| `list_pages` | List all pages |
+| `get_page` | Get a single page by slug |
+| `create_page` | Create a new page |
+| `update_page` | Edit an existing page |
+| `delete_page` | Permanently delete a page |
+
+---
+
+## Notes
+
+- **API key is never stored in code** — it's always read from the `MATAROA_API_KEY` environment variable.
+- **Mataroa has no rate limiting**, so you can make requests freely.
+- **Blog-level settings** (title, custom domain, etc.) are not accessible via the Mataroa API and therefore not exposed here.
+- Draft posts have `published_at: null`. Publishing sets it to a date; unpublishing clears it.
+
+---
+
+## Running tests
+
+```bash
+# Unit tests (no API key needed)
+pip install -e .
+pip install pytest pytest-asyncio respx
+pytest tests/test_client.py tests/test_server.py -v
+
+# Integration tests (requires a real Mataroa API key)
+MATAROA_API_KEY=your-key pytest tests/test_integration.py --run-integration -v
+```
+
+---
+
+## License
+
+MIT

mataroa_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mataroa-mcp"
+version = "0.1.0"
+description = "MCP server for managing a Mataroa blog via natural language"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+mataroa-mcp = "mataroa_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mataroa_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"
+asyncio_mode = "auto"
+
+[tool.hatch.envs.default]
+dependencies = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]
+
+[tool.hatch.envs.default.scripts]
+test = "pytest tests/test_client.py tests/test_server.py"
+test-all = "pytest"

mataroa_mcp-0.1.0/src/mataroa_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Mataroa MCP server — manage your Mataroa blog through natural language."""
+
+__version__ = "0.1.0"

mataroa_mcp-0.1.0/src/mataroa_mcp/client.py

@@ -0,0 +1,142 @@
+"""Thin async wrapper around the Mataroa REST API using httpx."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+BASE_URL = "https://mataroa.blog/api"
+TIMEOUT = 30.0
+
+
+class MataroaClient:
+    def __init__(self, api_key: str) -> None:
+        self._headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            base_url=BASE_URL,
+            headers=self._headers,
+            timeout=TIMEOUT,
+        )
+
+    # ── Posts ──────────────────────────────────────────────────────────────
+
+    async def list_posts(self) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get("/posts/")
+            return _parse(r)
+
+    async def get_post(self, slug: str) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get(f"/posts/{slug}/")
+            return _parse(r)
+
+    async def create_post(self, payload: dict[str, Any]) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.post("/posts/", json=payload)
+            return _parse(r)
+
+    async def update_post(self, slug: str, payload: dict[str, Any]) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.patch(f"/posts/{slug}/", json=payload)
+            return _parse(r)
+
+    async def delete_post(self, slug: str) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.delete(f"/posts/{slug}/")
+            return _parse(r)
+
+    # ── Comments ───────────────────────────────────────────────────────────
+
+    async def list_comments(self) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get("/comments/")
+            return _parse(r)
+
+    async def list_comments_for_post(self, slug: str) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get(f"/posts/{slug}/comments/")
+            return _parse(r)
+
+    async def list_pending_comments(self) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get("/comments/pending/")
+            return _parse(r)
+
+    async def get_comment(self, comment_id: int) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get(f"/comments/{comment_id}/")
+            return _parse(r)
+
+    async def approve_comment(self, comment_id: int) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.post(f"/comments/{comment_id}/approve/")
+            return _parse(r)
+
+    async def delete_comment(self, comment_id: int) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.delete(f"/comments/{comment_id}/")
+            return _parse(r)
+
+    # ── Pages ──────────────────────────────────────────────────────────────
+
+    async def list_pages(self) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get("/pages/")
+            return _parse(r)
+
+    async def get_page(self, slug: str) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.get(f"/pages/{slug}/")
+            return _parse(r)
+
+    async def create_page(self, payload: dict[str, Any]) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.post("/pages/", json=payload)
+            return _parse(r)
+
+    async def update_page(self, slug: str, payload: dict[str, Any]) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.patch(f"/pages/{slug}/", json=payload)
+            return _parse(r)
+
+    async def delete_page(self, slug: str) -> dict[str, Any]:
+        async with self._client() as c:
+            r = await c.delete(f"/pages/{slug}/")
+            return _parse(r)
+
+
+def _parse(response: httpx.Response) -> dict[str, Any]:
+    """Normalise every API response into a plain dict."""
+    status = response.status_code
+
+    if status == 204 or response.content == b"":
+        return {"ok": True}
+
+    try:
+        data = response.json()
+    except Exception:
+        return {
+            "ok": False,
+            "error": f"Mataroa API returned non-JSON response (HTTP {status})",
+        }
+
+    if status == 401:
+        return {"ok": False, "error": "Authentication failed. Check your MATAROA_API_KEY."}
+    if status == 404:
+        return {"ok": False, "error": data.get("detail", "Resource not found.")}
+    if status >= 500:
+        return {"ok": False, "error": f"Mataroa API server error (HTTP {status})."}
+    if status >= 400:
+        return {"ok": False, "error": data.get("detail", f"API error (HTTP {status}): {data}")}
+
+    # Successful responses don't always include an "ok" key — normalise.
+    if isinstance(data, dict) and "ok" not in data:
+        data["ok"] = True
+    return data

mataroa_mcp-0.1.0/src/mataroa_mcp/models.py

@@ -0,0 +1,63 @@
+"""Pydantic models for Mataroa API request/response objects."""
+
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel
+
+
+class Post(BaseModel):
+    title: str
+    slug: str
+    body: Optional[str] = None
+    published_at: Optional[str] = None
+    url: Optional[str] = None
+
+
+class PostCreate(BaseModel):
+    title: str
+    body: Optional[str] = None
+    published_at: Optional[str] = None
+
+
+class PostUpdate(BaseModel):
+    title: Optional[str] = None
+    slug: Optional[str] = None
+    body: Optional[str] = None
+    published_at: Optional[str] = None
+
+
+class Comment(BaseModel):
+    id: int
+    post_slug: str
+    post_title: str
+    post_url: str
+    url: str
+    created_at: str
+    name: str
+    email: Optional[str] = None
+    body: str
+    is_approved: bool
+    is_author: bool
+
+
+class Page(BaseModel):
+    title: str
+    slug: str
+    body: Optional[str] = None
+    is_hidden: bool = False
+    url: Optional[str] = None
+
+
+class PageCreate(BaseModel):
+    title: str
+    slug: str
+    body: Optional[str] = None
+    is_hidden: bool = False
+
+
+class PageUpdate(BaseModel):
+    title: Optional[str] = None
+    slug: Optional[str] = None
+    body: Optional[str] = None
+    is_hidden: Optional[bool] = None