@baruchiro/paperless-mcp 0.0.0-test1

package/.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

package/.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "restricted",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.cursor/rules/http-transport.mdc

@@ -0,0 +1,13 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+# HTTP Transport Mode for MCP Server
+
+- The MCP server can run in HTTP mode using the `--http` CLI flag.
+- When `--http` is set, the entrypoint [src/index.ts](mdc:src/index.ts) starts an Express server and exposes the MCP API at `/mcp`.
+- Each POST to `/mcp` creates a new `McpServer` and `StreamableHTTPServerTransport` for stateless, isolated handling.
+- The HTTP port can be set with `--port` (default: 3000).
+- Express must be installed as a dependency for HTTP mode.
+- If `--http` is not set, the server runs in stdio mode as before.

package/.cursor/rules/types-usage.mdc

@@ -0,0 +1,18 @@
+---
+description: Ensuring all API and tool response types are defined and reused from a dedicated types file for consistency and maintainability.
+globs: 
+alwaysApply: false
+---
+# Type Usage and Expectations
+
+- All core logic is implemented in TypeScript (.ts files), as described in [README.md](mdc:README.md).
+- Type safety is enforced throughout the codebase, especially for:
+  - API responses (e.g., from PaperlessAPI)
+  - Tool callback signatures (see [src/tools/tags.ts](mdc:src/tools/tags.ts))
+  - Server interactions using `@modelcontextprotocol/sdk` types (e.g., `CallToolResult`)
+- Types for API responses should be defined in a dedicated file (e.g., `src/api/types.ts`), and imported where needed for clarity and maintainability.
+- When defining tools, always use the correct callback signature and return types as required by the SDK.
+- Prefer explicit type annotations for function arguments and return values, especially for exported functions and tool handlers.
+- Use Zod schemas for runtime validation of tool arguments where applicable.
+
+This ensures robust type checking and predictable behavior across the MCP server implementation.

package/.cursor/rules/typescript-mcp-migration.mdc

@@ -0,0 +1,12 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+# TypeScript MCP Server Migration
+
+- The main entrypoint is [src/index.ts](mdc:src/index.ts), which starts an MCP server for Paperless-NGX using the @modelcontextprotocol/sdk package.
+- All core logic is now in TypeScript; all main files in src/ use the .ts extension.
+- The MCP server is started using `McpServer` and `StdioServerTransport` from the SDK, with `await server.connect(transport)`.
+- The project can be run directly in TypeScript using the npm script: `npm run start -- <baseUrl> <token>` (see [package.json](mdc:package.json)).
+- Node.js types are provided by @types/node in devDependencies.

package/.dockerignore

@@ -0,0 +1,2 @@
+node_modules
+build 

package/.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: [baruchiro] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

package/.github/workflows/docker-publish.yml

@@ -0,0 +1,57 @@
+name: Docker Publish
+on:
+  workflow_call:
+    inputs:
+      versionTag:
+        required: false
+        type: string
+  pull_request:
+    branches:
+      - master
+      - main
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Set semver and latest tags if release
+        id: tagmeta
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_call" ]; then
+            echo "SEMVER=type=semver,pattern=${{ inputs.versionTag }}" >> $GITHUB_OUTPUT
+            echo "LATEST=type=raw,value=latest" >> $GITHUB_OUTPUT
+          else
+            echo "SEMVER=" >> $GITHUB_OUTPUT
+            echo "LATEST=" >> $GITHUB_OUTPUT
+          fi
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.actor }}/${{ github.repository }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=sha
+            ${{ steps.tagmeta.outputs.SEMVER }}
+            ${{ steps.tagmeta.outputs.LATEST }}
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

package/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    outputs:
+      hasChangesets: ${{ steps.changesets.outputs.hasChangesets }}
+      versionTag: ${{ steps.version.outputs.VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+      - name: Install dependencies
+        run: npm ci
+      - name: Create Release Pull Request
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          publish: npm publish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Extract version from publishedPackages
+        id: version
+        run: |
+          echo "VERSION=$(echo '${{ steps.changesets.outputs.publishedPackages }}' | jq -r '.[0].version')" >> $GITHUB_OUTPUT
+
+  docker-publish:
+    needs: release
+    if: needs.release.outputs.hasChangesets == 'false'
+    uses: ./.github/workflows/docker-publish.yml
+    with:
+      versionTag: ${{ needs.release.outputs.versionTag }}
+    secrets: inherit

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+All participants are expected to uphold a respectful and inclusive environment. Harassment or discrimination of any kind will not be tolerated.
+
+If you experience or witness unacceptable behavior, please report it by opening an issue or contacting the maintainer directly.

package/CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to paperless-mcp
+
+Thank you for your interest in contributing!
+
+## How to Contribute
+- Fork the repository
+- Create a new branch for your feature or bugfix
+- Make your changes
+- Open a pull request with a clear description
+
+## Reporting Issues
+- Please use GitHub Issues for bug reports and feature requests
+- Include as much detail as possible
+
+## Code Style
+- Use TypeScript for all new code
+- Follow existing code patterns

package/Dockerfile

@@ -0,0 +1,19 @@
+# Builder stage
+FROM node:20-slim AS builder
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-slim AS production
+
+WORKDIR /app
+COPY --from=builder /app/build .
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/package.json ./package.json
+COPY --from=builder /app/package-lock.json ./package-lock.json
+
+EXPOSE 3000
+ENTRYPOINT [ "node", "index.js", "--http", "--port", "3000" ]

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2024 Baruch Odem
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.