matrix-mcp 0.1.0__tar.gz

matrix_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build package
+        run: uv build
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run pre-commit (via prek)
+        uses: j178/prek-action@v1

matrix_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/matrix-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Build
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

matrix_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+.ruff_cache/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.matrix-mcp/
+src/matrix_mcp/_version.py

matrix_mcp-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,33 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.9
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (type checker)
+        entry: uv run mypy src tests
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: ty
+        name: ty (type checker)
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false

matrix_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,7 @@
+# Matrix MCP
+
+This repository is a generic Matrix MCP server.
+
+Do not include deployment-specific names, internal domains, company names, private OAuth-provider details, private Matrix room IDs, private Matrix user IDs, or production logs in source, docs, tests, commit messages, issues, or pull requests.
+
+Keep the package useful for any Matrix homeserver and any MCP client.

matrix_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: matrix-mcp
+Version: 0.1.0
+Summary: A Matrix MCP server for connecting coding agents to Matrix and MindRoom conversations.
+Author: MindRoom
+License-Expression: MIT
+Requires-Python: >=3.12
+Requires-Dist: fastmcp>=2.12
+Requires-Dist: mindroom-nio>=0.25
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: pydantic-settings>=2.9
+Requires-Dist: pydantic>=2.11
+Requires-Dist: rich>=14.0
+Requires-Dist: typer>=0.16
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.4; extra == 'dev'
+Requires-Dist: ruff>=0.13; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Matrix MCP
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
+[![Docs](https://img.shields.io/badge/docs-plugins-blue)](https://docs.mindroom.chat/plugins/)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io/)
+
+<img src="https://media.githubusercontent.com/media/mindroom-ai/mindroom/refs/heads/main/frontend/public/logo.png" alt="MindRoom Logo" align="right" width="120" />
+
+Local-first Matrix access for MCP clients.
+
+Matrix MCP lets Claude Code and other MCP clients read and write Matrix rooms.
+It is intended to make MindRoom conversations available to local coding agents without giving hosted agents access to the local filesystem.
+
+## Install
+
+```bash
+uv tool install git+https://github.com/mindroom-ai/matrix-mcp
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+```
+
+## Login
+
+Matrix SSO:
+
+```bash
+matrix-mcp auth sso https://matrix.example.com
+```
+
+Existing Matrix access token:
+
+```bash
+matrix-mcp auth token https://matrix.example.com @alice:example.com "$MATRIX_ACCESS_TOKEN" --device-id DEVICEID
+```
+
+Password auth, when enabled by the homeserver:
+
+```bash
+matrix-mcp auth password https://matrix.example.com @alice:example.com
+```
+
+Credentials are stored in the user config directory reported by:
+
+```bash
+matrix-mcp config-path
+```
+
+## Claude Code
+
+Add the local MCP server:
+
+```bash
+claude mcp add matrix -- matrix-mcp serve
+```
+
+The server runs over stdio. It does not expose a local HTTP port during normal MCP operation.
+
+## Tools
+
+- `matrix_whoami`: show the configured Matrix user/device.
+- `matrix_list_rooms`: list rooms joined by the authenticated user.
+- `matrix_read_room_recent`: read recent text events from a room.
+- `matrix_send_message`: send a text message, optionally as a Matrix thread reply.
+
+The tool instructions tell clients to prefer read tools first and only send messages when the user explicitly asks.
+
+## Development
+
+```bash
+uv run --extra dev pytest
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+uv run --extra dev mypy src tests
+uv run --extra dev ty check
+uv build
+```

matrix_mcp-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Matrix MCP
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mindroom-ai/matrix-mcp/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/matrix-mcp.svg)](https://pypi.org/project/matrix-mcp/)
+[![Docs](https://img.shields.io/badge/docs-plugins-blue)](https://docs.mindroom.chat/plugins/)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io/)
+
+<img src="https://media.githubusercontent.com/media/mindroom-ai/mindroom/refs/heads/main/frontend/public/logo.png" alt="MindRoom Logo" align="right" width="120" />
+
+Local-first Matrix access for MCP clients.
+
+Matrix MCP lets Claude Code and other MCP clients read and write Matrix rooms.
+It is intended to make MindRoom conversations available to local coding agents without giving hosted agents access to the local filesystem.
+
+## Install
+
+```bash
+uv tool install git+https://github.com/mindroom-ai/matrix-mcp
+```
+
+For local development:
+
+```bash
+uv sync --extra dev
+```
+
+## Login
+
+Matrix SSO:
+
+```bash
+matrix-mcp auth sso https://matrix.example.com
+```
+
+Existing Matrix access token:
+
+```bash
+matrix-mcp auth token https://matrix.example.com @alice:example.com "$MATRIX_ACCESS_TOKEN" --device-id DEVICEID
+```
+
+Password auth, when enabled by the homeserver:
+
+```bash
+matrix-mcp auth password https://matrix.example.com @alice:example.com
+```
+
+Credentials are stored in the user config directory reported by:
+
+```bash
+matrix-mcp config-path
+```
+
+## Claude Code
+
+Add the local MCP server:
+
+```bash
+claude mcp add matrix -- matrix-mcp serve
+```
+
+The server runs over stdio. It does not expose a local HTTP port during normal MCP operation.
+
+## Tools
+
+- `matrix_whoami`: show the configured Matrix user/device.
+- `matrix_list_rooms`: list rooms joined by the authenticated user.
+- `matrix_read_room_recent`: read recent text events from a room.
+- `matrix_send_message`: send a text message, optionally as a Matrix thread reply.
+
+The tool instructions tell clients to prefer read tools first and only send messages when the user explicitly asks.
+
+## Development
+
+```bash
+uv run --extra dev pytest
+uv run --extra dev ruff check .
+uv run --extra dev ruff format --check .
+uv run --extra dev mypy src tests
+uv run --extra dev ty check
+uv build
+```

matrix_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,96 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "matrix-mcp"
+dynamic = ["version"]
+description = "A Matrix MCP server for connecting coding agents to Matrix and MindRoom conversations."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+authors = [{ name = "MindRoom" }]
+dependencies = [
+  "fastmcp>=2.12",
+  "mindroom-nio>=0.25",
+  "platformdirs>=4.3",
+  "pydantic>=2.11",
+  "pydantic-settings>=2.9",
+  "rich>=14.0",
+  "typer>=0.16",
+]
+
+[project.optional-dependencies]
+dev = [
+  "mypy>=1.14",
+  "pre-commit>=4",
+  "pytest>=8.4",
+  "pytest-asyncio>=1.0",
+  "ruff>=0.13",
+  "ty",
+]
+
+[project.scripts]
+matrix-mcp = "matrix_mcp.cli:app"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/matrix_mcp/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/matrix_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+  "D",       # pydocstyle
+  "ANN",     # annotations
+  "COM812",  # trailing comma
+  "ISC001",  # implicit string concat
+  "T20",     # print statements are acceptable for CLI output
+]
+
+[tool.ruff.lint.per-file-ignores]
+"src/matrix_mcp/cli.py" = [
+  "B008",    # Typer uses Option/Argument defaults intentionally
+  "FBT001",  # Typer boolean options are command-line flags
+  "FBT003",  # Typer boolean option defaults are command-line flag defaults
+  "PLR0913", # CLI commands naturally expose several command-line options
+  "TC003",   # Typer resolves annotations at runtime
+]
+"src/matrix_mcp/config.py" = [
+  "S105", # redaction placeholder is intentionally not a real token
+]
+"tests/*" = [
+  "S101",    # assert usage is fine in tests
+  "PLR2004", # magic values are fine in tests
+  "S105",    # test tokens
+  "S106",    # test tokens
+]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+packages = ["matrix_mcp"]
+
+[[tool.mypy.overrides]]
+module = ["nio"]
+ignore_missing_imports = true
+
+[tool.ty.rules]
+unused-ignore-comment = "ignore"

matrix_mcp-0.1.0/src/matrix_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""Matrix MCP package."""
+
+__all__ = ["__version__"]
+
+try:
+    from matrix_mcp._version import __version__
+except ImportError:
+    __version__ = "0.0.0"

matrix_mcp-0.1.0/src/matrix_mcp/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

matrix_mcp-0.1.0/src/matrix_mcp/auth.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, quote, urlencode, urlsplit
+
+from nio import AsyncClient, LoginResponse
+from pydantic import BaseModel
+
+from matrix_mcp.config import MatrixMCPConfig
+
+
+class LoginResult(BaseModel):
+    homeserver: str
+    user_id: str
+    device_id: str | None
+    access_token: str
+
+    def to_config(self) -> MatrixMCPConfig:
+        return MatrixMCPConfig(
+            homeserver=self.homeserver,
+            user_id=self.user_id,
+            device_id=self.device_id,
+            access_token=self.access_token,
+        )
+
+
+def build_sso_redirect_url(*, homeserver: str, redirect_url: str, idp_id: str | None = None) -> str:
+    base = homeserver.rstrip("/")
+    provider = f"/{quote(idp_id, safe='')}" if idp_id else ""
+    query = urlencode({"redirectUrl": redirect_url})
+    return f"{base}/_matrix/client/v3/login/sso/redirect{provider}?{query}"
+
+
+def extract_login_token(query: str) -> str:
+    values = parse_qs(query, keep_blank_values=False)
+    token = values.get("loginToken", [None])[0]
+    if not token:
+        msg = "Matrix SSO callback did not include loginToken"
+        raise ValueError(msg)
+    return token
+
+
+class SSOCallbackServer:
+    def __init__(self, *, host: str = "127.0.0.1", port: int = 8767) -> None:
+        self.token: str | None = None
+        self.error: Exception | None = None
+
+        owner = self
+
+        class CallbackHandler(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                try:
+                    owner.token = extract_login_token(urlsplit(self.path).query)
+                    self.send_response(200)
+                    self.end_headers()
+                    self.wfile.write(b"Matrix MCP login complete. You can close this tab.")
+                except Exception as exc:  # noqa: BLE001
+                    owner.error = exc
+                    self.send_response(400)
+                    self.end_headers()
+                    self.wfile.write(b"Matrix MCP login failed. Return to the terminal.")
+
+            def log_message(self, format: str, *_args: object) -> None:  # noqa: A002
+                del format, _args
+
+        self._server = HTTPServer((host, port), CallbackHandler)
+        self.redirect_url = f"http://{host}:{self._server.server_port}/callback"
+
+    def wait_for_token(self) -> str:
+        self._server.handle_request()
+        self._server.server_close()
+        if self.error is not None:
+            raise self.error
+        if self.token is None:
+            msg = "Matrix SSO callback did not complete"
+            raise RuntimeError(msg)
+        return self.token
+
+
+async def login_with_password(
+    *,
+    homeserver: str,
+    user: str,
+    password: str,
+    device_name: str = "matrix-mcp",
+) -> LoginResult:
+    client = AsyncClient(homeserver.rstrip("/"), user)
+    try:
+        response = await client.login(password=password, device_name=device_name)
+    finally:
+        await client.close()
+    if isinstance(response, LoginResponse):
+        return LoginResult(
+            homeserver=homeserver.rstrip("/"),
+            user_id=response.user_id,
+            device_id=response.device_id,
+            access_token=response.access_token,
+        )
+    msg = f"Matrix password login failed: {response}"
+    raise RuntimeError(msg)
+
+
+async def login_with_token(
+    *,
+    homeserver: str,
+    login_token: str,
+    device_name: str = "matrix-mcp",
+) -> LoginResult:
+    client = AsyncClient(homeserver.rstrip("/"))
+    try:
+        response = await client.login(token=login_token, device_name=device_name)
+    finally:
+        await client.close()
+    if isinstance(response, LoginResponse):
+        return LoginResult(
+            homeserver=homeserver.rstrip("/"),
+            user_id=response.user_id,
+            device_id=response.device_id,
+            access_token=response.access_token,
+        )
+    msg = f"Matrix token login failed: {response}"
+    raise RuntimeError(msg)