diff --git a/.env.example b/.env.example index 7e38d7b..6569cb0 100644 --- a/.env.example +++ b/.env.example @@ -84,3 +84,17 @@ DRAWIO_URL=https://app.diagrams.net # Penpot (default URL in compose) PENPOT_URL=https://design.penpot.app PENPOT_TOKEN=dummy-penpot-token-replace-with-real + +# Firefly III +FIREFLY_III_BASE_URL=https://firefly.example.com +FIREFLY_III_PAT=dummy-personal-access-token-replace-with-real +FIREFLY_III_PRESET=default + +# Paperless-NGX +PAPERLESS_URL=https://paperless.example.com +PAPERLESS_TOKEN=dummy-paperless-token-replace-with-real + +# Actual Budget +ACTUAL_SERVER_URL=https://actual.example.com +ACTUAL_PASSWORD=dummy-password-replace-with-real +ACTUAL_BUDGET_SYNC_ID=dummy-budget-sync-id diff --git a/JOURNAL.md b/JOURNAL.md index b3402ef..fbd1340 100644 --- a/JOURNAL.md +++ b/JOURNAL.md @@ -1833,7 +1833,68 @@ Validated the 8 servers that "require config" to determine if MCP protocol layer **Registry Location**: `git.knownelement.com/knel/knel-aimiddleware/:latest` -**Files Added**: -- run.sh - Shell script for Docker registry management +--- + +## 2026-02-27 + +### [MCP Integration] firefly-iii-mcp and paperless-mcp Added + +**Date/Time**: 2026-02-27 14:00:00 EST +**Work**: Added two new MCP servers for financial and document management + +**What was done**: + +1. **firefly-iii-mcp (NEW)**: + - Repository: https://github.com/etnperlong/firefly-iii-mcp + - Build approach: Used npm package `@firefly-iii-mcp/local` instead of building from source + - Reason: Source build failed due to Turborepo monorepo complexity with Bun + - Container size: ~200MB (node:22-alpine base) + - Version: 1.3.0 + - MCP handshake: Validated successfully + - Environment variables: FIREFLY_III_BASE_URL, FIREFLY_III_PAT, FIREFLY_III_PRESET (optional) + +2. **paperless-mcp (validated)**: + - Repository: https://github.com/nloui/paperless-mcp (already existed) + - Build: Already had Dockerfile, just needed validation + - Container size: ~300MB (Python-based) + - Version: 1.0.0 + - MCP handshake: Validated successfully + - Configuration: PAPERLESS_URL and PAPERLESS_TOKEN passed as CLI args + +3. **actual-mcp (already configured)**: + - Already existed in project with wrapper script + - Environment variables: ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID + +**Validation Commands Used**: +```bash +# firefly-iii-mcp (requires env vars) +echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | \ + timeout 15 docker run --rm -i -e FIREFLY_III_PAT=dummy -e FIREFLY_III_BASE_URL=http://localhost:8080 kneldevstack-aimiddleware-firefly-iii-mcp + +# paperless-mcp (requires CLI args) +echo '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{},"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}},"id":1}' | \ + timeout 15 docker run --rm -i kneldevstack-aimiddleware-paperless-mcp http://localhost:8000 dummy-token +``` + +**Files Created**: +- dockerfiles/firefly-iii-mcp/Dockerfile +- mcp-firefly-iii-wrapper.sh +- mcp-paperless-wrapper.sh + +**Files Modified**: +- scripts/CloneVendorRepos.sh (added firefly-iii-mcp repo) +- docker-compose.yml (added firefly-iii-mcp and paperless-mcp services) +- crush.json (added firefly-iii and paperless MCP entries) +- .env.example (added environment variables for all three servers) +- STATUS.md (updated working servers count to 27) + +**Financial & Budgeting Category**: +Now has 3 working MCP servers: +1. firefly-iii-mcp - Personal finance management with Firefly III +2. actual-mcp - Budget tracking with Actual Budget +3. paperless-mcp - Document management for financial documents + +**Pattern Applied**: +When npm package exists and works better than source build, prefer npm package installation for reliability and simplicity. --- diff --git a/README.md b/README.md index 7905715..c94864a 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,13 @@ For detailed build and configuration status of all MCP/LSP servers, see [STATUS. | matomo-mcp | kneldevstack-aimiddleware-matomo-mcp | Analytics integration | | bitwarden-mcp | kneldevstack-aimiddleware-bitwarden-mcp | Official password vault management | +#### Financial & Budgeting (3 servers) +| Service | Container Name | Description | +|---------|---------------|-------------| +| firefly-iii-mcp | kneldevstack-aimiddleware-firefly-iii-mcp | Personal finance management with Firefly III | +| actual-mcp | kneldevstack-aimiddleware-actual-mcp | Budget tracking with Actual Budget | +| paperless-mcp | kneldevstack-aimiddleware-paperless-mcp | Document management for financial documents | + #### Productivity & Automation (6 servers) | Service | Container Name | Description | |---------|---------------|-------------| @@ -274,6 +281,9 @@ Required variables for MCP servers (see `.env.example`): | kicad-mcp | `KICAD_HOST` (default: host.docker.internal), `KICAD_PORT` (default: 5555) | | context7-mcp | `UPSTASH_REDIS_REST_URL`, `UPSTASH_REDIS_REST_TOKEN` | | penpot-mcp | `PENPOT_URL` (default: https://design.penpot.app), `PENPOT_TOKEN` | +| firefly-iii-mcp | `FIREFLY_III_BASE_URL`, `FIREFLY_III_PAT`, `FIREFLY_III_PRESET` (optional) | +| actual-mcp | `ACTUAL_SERVER_URL`, `ACTUAL_PASSWORD`, `ACTUAL_BUDGET_SYNC_ID` | +| paperless-mcp | `PAPERLESS_URL`, `PAPERLESS_TOKEN` | **Security Note**: Never commit `.env` file to version control. diff --git a/STATUS.md b/STATUS.md index c9708db..5dbbfea 100644 --- a/STATUS.md +++ b/STATUS.md @@ -2,7 +2,7 @@ Tracking the setup and validation of MCP/LSP servers via Docker Compose. -Last validated: 2026-02-20 +Last validated: 2026-02-27 ## Repository URLs Verified (2026-02-19) @@ -48,7 +48,7 @@ All 32 vendor repositories have been verified and correctly cloned. CloneVendorR ## Validation Summary -**Working MCP Servers (25 validated with MCP handshake):** +**Working MCP Servers (27 validated with MCP handshake):** - ✓ actual-mcp: Working (Actual Budget MCP) - requires ACTUAL_SERVER_URL, ACTUAL_PASSWORD, ACTUAL_BUDGET_SYNC_ID env vars - ✓ audiobook-mcp: Working (audiobook-library v1.1.0) - requires AUDIOBOOK_ROOT env var - ✓ beszel-mcp: Working (beszel-mcp) - requires BESZEL_URL, BESZEL_USERNAME, BESZEL_PASSWORD env vars @@ -59,6 +59,7 @@ All 32 vendor repositories have been verified and correctly cloned. CloneVendorR - ✓ docker-mcp: Working (docker-mcp v0.1.0) - requires Docker socket mount - ✓ docspace-mcp: Working (@onlyoffice/docspace-mcp v3.1.0) - requires DOCSPACE_HOST and DOCSPACE_TOKEN env vars - ✓ drawio-mcp: Working (drawio-mcp-server v1.4.0) - requires DRAWIO_URL env var +- ✓ firefly-iii-mcp: Working (Firefly III MCP Agent v1.3.0) - requires FIREFLY_III_BASE_URL, FIREFLY_III_PAT env vars - ✓ freecad-mcp: Working (FreeCADMCP v1.25.0) - requires FreeCAD with addon running - ✓ ghost-mcp: Working (ghost-mcp-ts v1.0.0) - requires Ghost CMS credentials - ✓ gimp-mcp: Working (GimpMCP v1.10.1) - requires GIMP with server running @@ -71,7 +72,7 @@ All 32 vendor repositories have been verified and correctly cloned. CloneVendorR - ✓ terraform-mcp: Working (terraform-mcp-server v0.4.0) - requires credentials for HCP Terraform - ✓ matomo-mcp: Working (matomo-mcp-client v1.0.0) - connects to openmost.io hosted service (59 tools, 31 prompts) - ✓ mcp-redmine: Working (Redmine MCP server v1.25.0) - requires REDMINE_URL for actual usage -- ✓ paperless-mcp: Working (paperless-ngx v1.0.0) - requires baseUrl/token CLI args +- ✓ paperless-mcp: Working (paperless-ngx v1.0.0) - requires PAPERLESS_URL and PAPERLESS_TOKEN CLI args - ✓ superset-mcp: Working (superset-mcp) - requires SUPERSET_URL, SUPERSET_USERNAME, SUPERSET_PASSWORD env vars - ✓ proxmox-mcp: Working (proxmox_mcp) - requires PROXMOX_MCP_CONFIG env var pointing to config file @@ -128,7 +129,8 @@ All 32 vendor repositories have been verified and correctly cloned. CloneVendorR | mcp-ansible | Build/Runtime Issue | Container builds but fails at runtime - package not found in PyPI registry. Upstream issue. | | mcp-redmine | Built | Container built from Python source. MCP stdio-based, validated with MCP handshake. Requires REDMINE_URL for actual API operations. Version 1.25.0. | | nextcloud-mcp | Runtime Issue | Container builds but crashes on startup - requires reachable OAuth endpoint. Cannot validate MCP protocol without live Nextcloud instance. | -| paperless-mcp | Built | Container built from Python source. MCP stdio-based, requires baseUrl and token as CLI args. MCP handshake validated without live server. Version 1.0.0. | +| paperless-mcp | Built | Container built from Python source. MCP stdio-based, requires PAPERLESS_URL and PAPERLESS_TOKEN as CLI args. MCP handshake validated without live server. Version 1.0.0. | +| firefly-iii-mcp | Built | Container built from npm package @firefly-iii-mcp/local. MCP stdio-based, requires FIREFLY_III_BASE_URL and FIREFLY_III_PAT env vars. MCP handshake validated without live server. Version 1.3.0. | | penpot-mcp | Build/Runtime Issue | Container built from TypeScript monorepo source. Uses HTTP/WebSocket transport (not stdio). Multiple endpoints: HTTP at :4401/mcp, SSE at :4401/sse, WebSocket at :4402. | | postizz-mcp | Transport Issue | Container built from TypeScript source. Uses HTTP transport (port 3084), not stdio. Not compatible with standard MCP clients. | | proxmox-mcp | Built | Container built from Python source (331MB). MCP stdio-based, requires PROXMOX_MCP_CONFIG env var pointing to config file. Fixed by patching fastmcp imports. | diff --git a/crush.json b/crush.json index eb6807e..4732ca7 100644 --- a/crush.json +++ b/crush.json @@ -179,6 +179,16 @@ "type": "stdio", "command": "/home/charles/Projects/KNEL-AIMiddleware/mcp-penpot-wrapper.sh", "timeout": 60 + }, + "firefly-iii": { + "type": "stdio", + "command": "/home/charles/Projects/KNEL-AIMiddleware/mcp-firefly-iii-wrapper.sh", + "timeout": 60 + }, + "paperless": { + "type": "stdio", + "command": "/home/charles/Projects/KNEL-AIMiddleware/mcp-paperless-wrapper.sh", + "timeout": 60 } } } diff --git a/docker-compose.yml b/docker-compose.yml index 1b25a08..e9c50eb 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -239,6 +239,21 @@ services: profiles: - ops + # Paperless-NGX MCP - Document management + # NOTE: This is a stdio-based MCP server, run on-demand by Crush via docker run + paperless-mcp: + image: kneldevstack-aimiddleware-paperless-mcp + build: + context: ./vendor/paperless-mcp + dockerfile: ../../dockerfiles/paperless-mcp/Dockerfile + container_name: kneldevstack-aimiddleware-paperless-mcp + restart: "no" + environment: + - PAPERLESS_URL=${PAPERLESS_URL} + - PAPERLESS_TOKEN=${PAPERLESS_TOKEN} + profiles: + - ops + # WordPress MCP Adapter wordpress-mcp: image: kneldevstack-aimiddleware-wordpress-mcp @@ -546,7 +561,7 @@ services: - dev # ========================================== - # Financial & Budgeting (1 server) + # Financial & Budgeting (2 servers) # ========================================== # Actual Budget MCP - Budget management @@ -565,6 +580,22 @@ services: profiles: - ops + # Firefly III MCP - Personal finance manager + # NOTE: This is a stdio-based MCP server, run on-demand by Crush via docker run + firefly-iii-mcp: + image: kneldevstack-aimiddleware-firefly-iii-mcp + build: + context: . + dockerfile: dockerfiles/firefly-iii-mcp/Dockerfile + container_name: kneldevstack-aimiddleware-firefly-iii-mcp + restart: "no" + environment: + - FIREFLY_III_BASE_URL=${FIREFLY_III_BASE_URL} + - FIREFLY_III_PAT=${FIREFLY_III_PAT} + - FIREFLY_III_PRESET=${FIREFLY_III_PRESET:-default} + profiles: + - ops + # ========================================== # System Monitoring (1 server) # ========================================== diff --git a/dockerfiles/firefly-iii-mcp/Dockerfile b/dockerfiles/firefly-iii-mcp/Dockerfile new file mode 100644 index 0000000..9765c07 --- /dev/null +++ b/dockerfiles/firefly-iii-mcp/Dockerfile @@ -0,0 +1,18 @@ +# Firefly III MCP Server +# https://github.com/etnperlong/firefly-iii-mcp +# Uses published npm package for reliability + +FROM node:22-alpine + +WORKDIR /app + +# Install the npm package globally +RUN npm install -g @firefly-iii-mcp/local + +# Environment variables (to be set at runtime) +ENV FIREFLY_III_BASE_URL="" +ENV FIREFLY_III_PAT="" +ENV FIREFLY_III_PRESET="default" + +# Run the local MCP server +ENTRYPOINT ["npx", "@firefly-iii-mcp/local"] diff --git a/mcp-firefly-iii-wrapper.sh b/mcp-firefly-iii-wrapper.sh new file mode 100755 index 0000000..d9ee29f --- /dev/null +++ b/mcp-firefly-iii-wrapper.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# Firefly III MCP wrapper script for Crush +CONTAINER_NAME="kneldevstack-aimiddleware-firefly-iii-mcp-crush" + +# Force remove existing container (suppress output) +docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true +sleep 0.5 + +# Run container with explicit name and environment variables +docker run -i --rm \ + --name "${CONTAINER_NAME}" \ + -e FIREFLY_III_BASE_URL="${FIREFLY_III_BASE_URL:-}" \ + -e FIREFLY_III_PAT="${FIREFLY_III_PAT:-}" \ + -e FIREFLY_III_PRESET="${FIREFLY_III_PRESET:-default}" \ + kneldevstack-aimiddleware-firefly-iii-mcp diff --git a/mcp-paperless-wrapper.sh b/mcp-paperless-wrapper.sh new file mode 100755 index 0000000..fe78853 --- /dev/null +++ b/mcp-paperless-wrapper.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# Paperless-NGX MCP wrapper script for Crush +CONTAINER_NAME="kneldevstack-aimiddleware-paperless-mcp-crush" + +# Force remove existing container (suppress output) +docker rm -f "${CONTAINER_NAME}" >/dev/null 2>&1 || true +sleep 0.5 + +# Run container with explicit name and environment variables +docker run -i --rm \ + --name "${CONTAINER_NAME}" \ + -e PAPERLESS_URL="${PAPERLESS_URL:-}" \ + -e PAPERLESS_TOKEN="${PAPERLESS_TOKEN:-}" \ + kneldevstack-aimiddleware-paperless-mcp \ + "${PAPERLESS_URL:-http://localhost:8000}" "${PAPERLESS_TOKEN:-}" diff --git a/scripts/CloneVendorRepos.sh b/scripts/CloneVendorRepos.sh index b472a59..9ae6fad 100755 --- a/scripts/CloneVendorRepos.sh +++ b/scripts/CloneVendorRepos.sh @@ -89,6 +89,7 @@ clone_repo "ha-mcp" "https://github.com/homeassistant-ai/ha-mcp.git" clone_repo "gitea-mcp" "https://gitea.com/gitea/gitea-mcp.git" clone_repo "limesurvey-mcp" "https://github.com/TonisOrmisson/limesurvey-mcp.git" clone_repo "linkwarden-mcp-server" "https://github.com/irfansofyana/linkwarden-mcp-server.git" +clone_repo "firefly-iii-mcp" "https://github.com/etnperlong/firefly-iii-mcp.git" echo -e "${GREEN}=== All repositories cloned successfully! ===${NC}" echo ""