docmost-mcp-remote 1.0.0__tar.gz

docmost_mcp_remote-1.0.0/.dockerignore

@@ -0,0 +1,10 @@
+.git
+.github
+.venv
+.env
+**/__pycache__
+.mypy_cache
+.pytest_cache
+.ruff_cache
+docs
+tests

docmost_mcp_remote-1.0.0/.env.example

@@ -0,0 +1,46 @@
+# Public https URL where MCP clients reach this server (behind your reverse proxy).
+PUBLIC_URL=https://mcp.example.com
+
+# Base URL of your Docmost instance.
+DOCMOST_URL=https://docs.example.com
+# Set to true only for a Docmost reachable over http on a trusted private network.
+DOCMOST_ALLOW_INSECURE_HTTP=false
+
+# Password for the bundled Postgres. Use a long random value.
+POSTGRES_PASSWORD=
+
+# Encrypts stored Docmost sessions and snapshots and signs cookies. At least 32 characters,
+# for example the output of: openssl rand -hex 32
+# Losing it signs every member out; leaking it together with the database
+# exposes their Docmost sessions.
+SECRET_KEY=
+# During a key rotation: the old key, so existing sessions stay readable.
+SECRET_KEY_PREVIOUS=
+
+# Comma-separated emails allowed to sign in. Empty allows every Docmost user.
+ALLOWED_EMAILS=
+
+# Comma-separated space slugs or ids members may use through this server.
+# Empty allows every space the member can see in Docmost.
+ALLOWED_SPACES=
+
+# When a member's Docmost session expires: "ask" them to sign in again (default),
+# or "stored_password" to keep their password encrypted and sign in automatically.
+RELOGIN_MODE=ask
+
+# Days page snapshots (copies of page bodies taken before every change) are kept.
+SNAPSHOT_RETENTION_DAYS=30
+# Days audit log entries (who called which tool on which page) are kept.
+AUDIT_RETENTION_DAYS=90
+# Tool calls one member may make per minute, over all their clients.
+TOOL_CALLS_PER_MINUTE=60
+
+# Reverse proxies whose X-Forwarded-For header is trusted for rate limiting.
+# The compose file publishes the port on 127.0.0.1 only and trusts every
+# client by default ("*"). Set the proxy's address if you publish it elsewhere.
+# FORWARDED_ALLOW_IPS=*
+
+LOG_LEVEL=info
+
+# Image tag. "1" follows 1.x releases; a full version such as 1.0.0 pins one.
+# IMAGE_TAG=1

docmost_mcp_remote-1.0.0/.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      python:
+        patterns: ["*"]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+  - package-ecosystem: docker
+    directory: /
+    schedule:
+      interval: weekly

docmost_mcp_remote-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,145 @@
+name: CI
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U test" --health-interval 2s --health-timeout 3s
+          --health-retries 30
+    env:
+      DATABASE_TEST_URL: postgresql://test:test@localhost:5432/test
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --locked
+      - name: Audit locked runtime dependencies
+        run: |
+          uv export --frozen --no-dev --no-emit-project --format requirements-txt -o requirements.txt
+          uv run pip-audit --strict --disable-pip --require-hashes -r requirements.txt
+
+  integration:
+    name: integration (Docmost ${{ matrix.docmost }})
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.canary }}
+    strategy:
+      fail-fast: false
+      matrix:
+        # Oldest supported, previous and newest tested release. "latest" warns early
+        # when a new Docmost release is out and the tested range needs a bump.
+        docmost: ["0.70.3", "0.96.0", "0.97.0"]
+        canary: [false]
+        include:
+          - docmost: latest
+            canary: true
+    services:
+      postgres:
+        image: postgres:17-alpine
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: test
+        ports:
+          - 5433:5432
+        options: >-
+          --health-cmd "pg_isready -U test" --health-interval 2s --health-timeout 3s
+          --health-retries 30
+    env:
+      DOCMOST_VERSION: ${{ matrix.docmost }}
+      DOCMOST_TEST_URL: http://localhost:3000
+      DATABASE_TEST_URL: postgresql://test:test@localhost:5433/test
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Start Docmost
+        run: docker compose -f tests/integration/compose.yaml up -d --wait --wait-timeout 180
+      - name: Wait for Docmost
+        run: |
+          for i in $(seq 1 90); do
+            if curl -fsS http://localhost:3000/api/health; then exit 0; fi
+            sleep 2
+          done
+          docker compose -f tests/integration/compose.yaml logs docmost
+          exit 1
+      - run: uv sync --locked
+      - run: uv run pytest tests/integration
+      - name: Docmost logs
+        if: failure()
+        run: docker compose -f tests/integration/compose.yaml logs docmost
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - name: Prepare .env
+        run: |
+          cp .env.example .env
+          sed -i "s/^POSTGRES_PASSWORD=$/POSTGRES_PASSWORD=ci-only/" .env
+          sed -i "s/^SECRET_KEY=$/SECRET_KEY=$(openssl rand -hex 32)/" .env
+          docker compose config --quiet
+      - name: Build the image
+        run: docker build -t ghcr.io/bbik52/docmost-mcp-remote:ci .
+      - name: Start the compose stack
+        run: IMAGE_TAG=ci docker compose up -d --wait --wait-timeout 120
+      - name: Smoke test
+        run: |
+          curl -fsS http://127.0.0.1:8000/healthz
+          curl -fsS -o /dev/null http://127.0.0.1:8000/login
+          test "$(curl -s -o /dev/null -w '%{http_code}' -X POST http://127.0.0.1:8000/mcp)" = 401
+          curl -fsS http://127.0.0.1:8000/.well-known/oauth-protected-resource/mcp
+          docker compose exec -T server docmost-mcp-remote admin members
+          test "$(docker image inspect -f '{{index .Config.Labels "io.modelcontextprotocol.server.name"}}' ghcr.io/bbik52/docmost-mcp-remote:ci)" = io.github.bbik52/docmost-mcp-remote
+      - name: Logs
+        if: always()
+        run: docker compose logs

docmost_mcp_remote-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,163 @@
+name: Release
+
+# Runs when a version tag such as v1.0.0 is pushed to master. Publishes the
+# package to PyPI, the image to ghcr.io, a GitHub release and the entry in the
+# official MCP Registry. See docs/RELEASING.md.
+
+on:
+  push:
+    tags: ["v[0-9]+.[0-9]+.[0-9]+"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/bbik52/docmost-mcp-remote
+  MCP_PUBLISHER_VERSION: v1.8.4
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Tag matches the project version and is on master
+        id: version
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          project="$(uv version --short)"
+          if [ "$version" != "$project" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match project version $project" >&2
+            exit 1
+          fi
+          git fetch --no-tags origin master
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/master; then
+            echo "Tag $GITHUB_REF_NAME is not on master" >&2
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - run: uv sync --locked
+      - name: Release metadata is consistent
+        run: uv run pytest tests/test_release_metadata.py
+      - name: Changelog has an entry for this version
+        run: grep -q "^## \[${{ steps.version.outputs.version }}\]" CHANGELOG.md
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+      - run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/docmost-mcp-remote/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  image:
+    needs: check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: docker/setup-qemu-action@v4
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+      - uses: docker/build-push-action@v7
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          annotations: ${{ steps.meta.outputs.annotations }}
+
+  github-release:
+    needs: [check, build, pypi, image]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          awk -v v="$VERSION" '
+            $0 ~ "^## \\[" v "\\]" { found = 1; next }
+            found && /^## \[/ { exit }
+            found { print }
+          ' CHANGELOG.md > notes.md
+          printf '\nImage: `%s:%s`\n' "$IMAGE" "$VERSION" >> notes.md
+          gh release create "$GITHUB_REF_NAME" dist/* --title "$VERSION" --notes-file notes.md --verify-tag
+
+  mcp-registry:
+    needs: [pypi, image]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: sigstore/cosign-installer@v4
+      - name: Download and verify mcp-publisher
+        run: |
+          set -euo pipefail
+          archive="mcp-publisher_linux_amd64.tar.gz"
+          base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
+          curl -fsSL -o "$archive" "$base_url/$archive"
+          curl -fsSL -o "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
+          cosign verify-blob \
+            --bundle "$archive.sigstore.json" \
+            --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
+            --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
+            "$archive"
+          tar xzf "$archive" mcp-publisher
+      - run: ./mcp-publisher validate
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

docmost_mcp_remote-1.0.0/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

docmost_mcp_remote-1.0.0/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org/). A release that needs attention
+when upgrading lists it under "Upgrade notes".
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-25
+
+First release.
+
+### Added
+
+- Remote MCP server (streamable HTTP at `/mcp`) for Docmost Community Edition
+  0.70.0 or newer.
+- Per-member sign-in with the member's own Docmost account; every tool call
+  runs as that member with their Docmost rights. Optional `ALLOWED_EMAILS`
+  and `ALLOWED_SPACES` limits.
+- OAuth 2.1 authorization server following the MCP authorization spec:
+  dynamic client registration, PKCE (S256), consent page with `read`,
+  `write` and `delete` scopes, resource-bound tokens, rotating refresh tokens
+  with reuse detection. Personal bearer tokens for scripts. Grants and tokens
+  are listed and revoked on the account page.
+- Read tools: `whoami`, `list_spaces`, `list_pages`, `recent_pages`,
+  `get_page` (Markdown), `search`, `list_comments`, `list_trash`,
+  `list_snapshots`. Page content is returned inside an untrusted-content
+  envelope.
+- Write tools: `create_page`, `update_page` (append, prepend, replace),
+  `rename_page`, `move_page`, `add_comment`, `restore_snapshot`; delete-scope
+  tools `trash_page` and `restore_page`. No permanent delete.
+- Encrypted snapshot of a page body before every change, kept for
+  `SNAPSHOT_RETENTION_DAYS`; read-back after every write to catch changes
+  Docmost did not apply.
+- Per-member rate limit (`TOOL_CALLS_PER_MINUTE`) and an audit log of tool
+  calls without content (`AUDIT_RETENTION_DAYS`).
+- `admin` command line: list members and grants, revoke grants or members,
+  disable members, read the audit log, rotate `SECRET_KEY`.
+- Database schema migrations applied at startup under a lock; an older
+  server refuses to start on a schema upgraded by a newer one.
+- Container image for linux/amd64 and linux/arm64, `compose.yaml` with
+  Postgres, and a PyPI package.

docmost_mcp_remote-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+Thanks for your interest. Issues and pull requests are welcome.
+
+## Ground rules
+
+- **Clean implementation.** Do not copy code, structure or tool descriptions
+  from docmost-mcp-oss or from Docmost (AGPL-3.0). Write from the observed
+  behavior of the Docmost HTTP API. See
+  [ADR 0001](docs/adr/0001-new-repository-from-scratch.md).
+- **English** for code, comments, docs, commit messages and pull requests.
+- Security-relevant changes need tests. Never log passwords, tokens, page
+  content or tool arguments.
+- Larger design changes start with an issue or an ADR in `docs/adr/`.
+- Database changes come with an Alembic migration in the same pull request
+  and follow "Database migrations" in [docs/DESIGN.md](docs/DESIGN.md):
+  never edit a released migration, keep existing data.
+
+## Setup
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.12 or newer.
+
+```sh
+uv sync
+docker run -d -p 5433:5432 -e POSTGRES_USER=test -e POSTGRES_PASSWORD=test postgres:17-alpine
+DATABASE_TEST_URL=postgresql://test:test@localhost:5433/test uv run pytest
+```
+
+Before pushing:
+
+```sh
+uv run ruff format .
+uv run ruff check .
+uv run mypy
+uv run pytest
+```
+
+## Pull requests
+
+- The repository uses git flow. Branch from `develop` as `feature/<topic>`
+  (or `bugfix/<topic>`) and open the pull request against `develop`.
+  `master` only receives `release/*` and `hotfix/*` merges and holds tagged
+  releases.
+- One topic per pull request.
+- Describe what changed and why; link the roadmap phase or issue.
+- CI must be green.
+- Changes to authentication, OAuth, tokens, cryptography, the sign-in and
+  consent pages or the write path are reviewed with extra care; see
+  "Contributions and project security" in [docs/DESIGN.md](docs/DESIGN.md).
+
+## License of contributions
+
+The project is licensed under the [Apache License 2.0](LICENSE). By opening a
+pull request you agree that your contribution is licensed under the same
+terms (section 5 of the license). There is no separate contributor agreement.