init

Author: ashkuc

.dockerignore

@@ -0,0 +1,24 @@
+.git
+.gitignore
+.vscode
+.idea
+.docker
+.env
+.env.*
+
+node_modules
+dist
+build
+
+*.md
+*.log
+*.tmp
+*.temp
+
+docker-compose.yml
+docker-compose.override.yml
+deploy
+postgres-init
+
+Dockerfile
+.dockerignore

.github/workflows/build-mcp-server-docker.yml

@@ -0,0 +1,58 @@
+name: Build MCP Server Docker Image
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  REGISTRY: ghcr.io
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify package version matches tag
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(jq -r .version mcp-server/package.json)
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match mcp-server/package.json version ($PKG_VERSION)"
+            exit 1
+          fi
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ github.repository }}/mcp-server
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/run-tests.yml

@@ -0,0 +1,48 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      integration:
+        description: Run integration tests (spins up Docker containers)
+        type: boolean
+        default: false
+
+jobs:
+  tests:
+    name: Run typecheck, lint, and tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Typecheck planka-api
+        run: pnpm --filter planka-api typecheck
+
+      - name: Build
+        run: pnpm build
+
+      - name: Typecheck mcp-server
+        run: pnpm --filter mcp-server typecheck
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Unit tests
+        run: pnpm test:unit
+      
+      - name: Integration tests
+        if: ${{ inputs.integration == true }}
+        run: pnpm test:integration

.gitignore

@@ -0,0 +1,62 @@
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Build outputs
+dist/
+build/
+out/
+
+# Package manager files
+package-lock.json
+yarn.lock
+.pnpm-store/
+
+# TypeScript
+*.tsbuildinfo
+.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.AppleDouble
+.LSOverride
+*.iml
+*.ipr
+*.iws
+
+# OS
+Thumbs.db
+Desktop.ini
+
+# Logs
+logs/
+*.log
+
+# Testing
+coverage/
+.nyc_output/
+*.lcov
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.temp
+
+# Docker
+.docker/
+docker-compose.override.yml

CONTRIBUTING.md

@@ -0,0 +1,43 @@
+# Contributing
+
+## Prerequisites
+
+- Node.js >= 22
+- pnpm
+- Docker + Docker Compose
+
+## Setup
+
+```bash
+pnpm install
+docker compose up -d
+docker compose exec postgres psql -U postgres -c 'CREATE DATABASE "charlieplan"'
+cp mcp-server/.env.example mcp-server/.env
+pnpm build
+```
+
+## Development
+
+```bash
+pnpm mcp:dev       # run MCP server in dev mode (stdio transport)
+pnpm typecheck     # type check all packages
+pnpm lint          # lint with Biome
+pnpm lint:fix      # auto-fix lint issues
+pnpm test:unit     # unit tests
+pnpm test:integration  # integration tests (requires Docker)
+```
+
+## Regenerating the Planka API client
+
+The `planka-api` package is generated from `planka-api/planka-swagger.json`.
+After editing the spec:
+
+```bash
+pnpm planka:generate
+```
+
+## Pull requests
+
+- Keep PRs focused — one concern per PR.
+- Run `pnpm typecheck && pnpm lint && pnpm test:unit` before submitting.
+- Describe _why_ the change is needed, not just what it does.

Dockerfile

@@ -0,0 +1,20 @@
+FROM node:22-slim AS base
+ENV PNPM_HOME="/pnpm"
+ENV PATH="$PNPM_HOME:$PATH"
+RUN corepack enable
+
+FROM base AS build
+WORKDIR /app
+COPY . .
+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
+
+RUN pnpm --filter mcp-server... run build
+
+RUN pnpm deploy --filter=mcp-server --prod /prod/mcp-server
+
+FROM base
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build /prod/mcp-server .
+EXPOSE 3000
+CMD ["node", "dist/index-sse.js"]

LICENSE

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

README.md

@@ -0,0 +1,53 @@
+# charlieplan-mcp
+
+MCP server that connects [Planka](https://planka.app) (self-hosted kanban) to AI assistants.
+
+## Why this exists
+
+AI chats are great for processing information — brainstorming, rewriting, distilling ideas from large amounts of text. But the output of that work — decisions, plans, next steps — needs to land somewhere.
+
+Planka is a simple, self-hosted kanban board. This server connects it to your AI workflow: results from chats turn into cards, cards provide context for future chats. The board becomes a persistent layer between sessions.
+
+![charlieplan-mcp](pepe-silvia-modified.png)
+
+## What it does
+
+Exposes Planka board management as MCP tools: projects, boards, lists, cards, labels, custom fields, task lists, attachments, and card search. Works with any MCP-compatible client (Claude Desktop, Claude.ai, etc.).
+
+When `SERVER_URL` is configured, the server also enables OAuth and a `/redirect` endpoint — deep links that bounce from a card directly into a chat with pre-filled context.
+
+## Local development
+
+**Prerequisites:** Docker, Node.js ≥ 22, pnpm, Claude Code
+
+```bash
+pnpm install
+```
+
+```bash
+docker compose up -d
+```
+
+```bash
+docker compose exec postgres psql -U postgres -c 'CREATE DATABASE "charlieplan"'
+```
+
+```bash
+cp mcp-server/.env.example mcp-server/.env
+```
+
+```bash
+pnpm build
+```
+
+Open [http://localhost:1337](http://localhost:1337) — login `admin@example.com` / `admin123` → Profile → API Keys → create a key.
+
+```bash
+claude mcp add planka -e PLANKA_API_KEY=<your-key> -- pnpm mcp:stdio
+```
+
+Done. Migrations run automatically on first connection. Verify with `claude mcp list`.
+
+## Self-hosting
+
+See [deploy.md](deploy.md).

SECURITY.md

@@ -0,0 +1,26 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please **do not** open a public GitHub issue for security vulnerabilities.
+
+Report them privately via [GitHub Security Advisories](../../security/advisories/new)
+or by emailing the maintainer directly (see the GitHub profile).
+
+Include:
+- A description of the vulnerability and its potential impact
+- Steps to reproduce or a proof-of-concept
+- Affected versions
+
+You can expect an acknowledgement within 72 hours and a fix or mitigation plan
+within 14 days for confirmed issues.
+
+## Scope
+
+This project handles:
+- Planka API tokens passed as Bearer credentials
+- OAuth authorization codes (PKCE flow, signed with `CODE_SECRET`)
+- Per-card metadata stored in a local PostgreSQL database
+
+Secrets are never logged or stored beyond their intended purpose.
+`CODE_SECRET` and Planka tokens are not persisted after use.