{"_id":"@berrylabs-id/flownest-mcp","_rev":"8-653bed74801801f4b3503a519c84c159","name":"@berrylabs-id/flownest-mcp","dist-tags":{"latest":"0.7.1"},"versions":{"0.1.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.1.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js"},"dist":{"shasum":"1f65eb91d3ed4824b21a408f9df4fd6774c49071","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.1.0.tgz","fileCount":7,"integrity":"sha512-YMCtjnVvkfTiQ9RuDOZpHkaaWtsSGFyYYq7Hq9NsVeTsZ2VvwzS4QsUZ9d2aO3kad0GVJzxWF7Nh4rVAMui8lw==","signatures":[{"sig":"MEQCIHPmkKIWfjz+9MwXLGn2orWqCWgpd4h1AQMT9BmWphNqAiA3nHxhCkZjMxUAfz9KjLieQaTiwSOplK6Xt0JuAgPR2Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35716},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"39ca34e30a13543d7165d38fa6e3dc463f75a390","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"Local stdio MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code or any MCP client via a Personal Access Token.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.1.0_1782191251055_0.1759235284353784","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@berrylabs-id/flownest-mcp","version":"0.1.1","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.1.1","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js"},"dist":{"shasum":"782cb43d102676e6770b62734aeadc0b5d2f9879","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.1.1.tgz","fileCount":7,"integrity":"sha512-CChmyt3S3Sk7VT6g3qeg0dkux1+R//HZRdVvEIsKN9ZrYtGxUvKrRBzQbMQNMgo+m3iNwa3ltjvC50ZiauejHQ==","signatures":[{"sig":"MEUCIQCdh0k/XVUpI3U8lPt0/uhbfSecMyO2I9Ov3ebPDXUbfAIgDVVwMyKz+AaJYeE36FV5K5GmoXTGRRnlM/4jesP1As8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":38506},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"6134112d22573e2de7d97be14832da14da0fa172","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"Local stdio MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code or any MCP client via a Personal Access Token.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.1.1_1782197210356_0.0722079587285378","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.2.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js"},"dist":{"shasum":"9d7e3afedf1602259258d74882a838191a3f7da3","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.2.0.tgz","fileCount":7,"integrity":"sha512-0LPudyqcIYlPbyGJJ1R74wSoIfyg2EifbahaLLxJc+0UohF7rMixAdMeCf9/3CsPyZwYLyrvT9udaQ0+K+JK5A==","signatures":[{"sig":"MEYCIQC7UGu8ATHdRV0sVbU8D30v18bKlEdwU4T30O3Dn5IxQgIhANEmP0UxvRX9s5ohBj9aNgnLhTQ0z0SwhG0d1NYB8GQG","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":43074},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"fe9493e6f688db61cb8d9cd13fab2c586ed0d5a9","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"Local stdio MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code or any MCP client via a Personal Access Token.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.2.0_1782204088784_0.20804323953188786","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.3.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.3.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js","flownest-mcp-http":"dist/http.js"},"dist":{"shasum":"ecb42b548cccbbf615eaa7414b0d9c6c694bf5f7","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.3.0.tgz","fileCount":12,"integrity":"sha512-9XJ5Y6Io8NnSkBJNh7qgnRmVCh+JCgNiR2A+rlEkfBkMv0fs6HbPWPsgGioPj1MtSFFA/o/kU7PLgyDaMulfiQ==","signatures":[{"sig":"MEQCIHwypHeQJYNDG90ApCupE+nmP4G0vALecSNKGgp5ujbCAiAjokFp8VXarqxuQlahsTxPOgNho+ihLbhNzNyxmrIWbg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":116846},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"1cf9872922691d0d3973d7acfa1eb40008e26b90","scripts":{"test":"node --test test/","build":"tsc","pretest":"npm run build","dev:http":"tsc --watch --preserveWatchOutput & node --watch dist/http.js","start:http":"node dist/http.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.0","express":"^5.2.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.3.0_1784715067042_0.9447141150904186","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.5.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.5.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js","flownest-mcp-http":"dist/http.js"},"dist":{"shasum":"165fe6ea89aa05ab3d74bbd653b946e99a63650b","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.5.0.tgz","fileCount":15,"integrity":"sha512-pPGsnV/92trjmC7YKFLpvXU/TxxebibCXYnSlCNgWRuA00KF1LV0Y2DuWetUUJCZnX/YdnoUjXwdJOhLATLGlg==","signatures":[{"sig":"MEUCIExGKl44uEaow4pxBzYvsqzgY4y2PV79r+YLDHiPt6AoAiEA4dntGo8LQkP4+PYLnfheosaHJMqFrw90bDRlawGZO9E=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":273326},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"7eb90f98bfc55c211289f689683739c91d8bd78a","scripts":{"test":"node --test test/*.test.js","build":"tsc","pretest":"npm run build","dev:http":"tsc --watch --preserveWatchOutput & node --watch dist/http.js","start:http":"node dist/http.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","express":"^5.2.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.5.0_1787400579915_0.31786822759068434","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.6.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.6.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js","flownest-mcp-http":"dist/http.js"},"dist":{"shasum":"352b301d91f75c0a3889f2b150c86dcfb6b61d13","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.6.0.tgz","fileCount":16,"integrity":"sha512-DJcixhI0mYMOZOrHr2vpRqFSyHg8bbP/ZRsgiIiqRpblsie0XuCoukf5HCHazahVl5RXHygsCzd0ma3QlQYLUg==","signatures":[{"sig":"MEYCIQDLoePB2lWehXlCmzrDLQ3q8Xf5/CRzTbwV70zW6dOg8AIhAJA2dQbSydSMVNN5/OxRI8YNux/BdP+elOaLoOVIg6R7","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":284399},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"8acbc38ad20b2e5a018fc14baef56181be92d586","scripts":{"test":"node --test test/*.test.js","build":"tsc","pretest":"npm run build","dev:http":"tsc --watch --preserveWatchOutput & node --watch dist/http.js","start:http":"node dist/http.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","express":"^5.2.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.6.0_1787405254960_0.15200539044888917","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@berrylabs-id/flownest-mcp","version":"0.7.0","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"license":"MIT","_id":"@berrylabs-id/flownest-mcp@0.7.0","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"bin":{"flownest-mcp":"dist/index.js","flownest-mcp-http":"dist/http.js"},"dist":{"shasum":"ee9390a069d4e8ff5b9f21b2f2c377e6c1e2f0e2","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.7.0.tgz","fileCount":18,"integrity":"sha512-1ihEd81akoZs8+SLw628NjbgMinGR6/zCR0KZ/FiSvD1IWYDTQ2cnXAHgBSuvqCyOQfbTKrlXSWP/Y8aBrcgFQ==","signatures":[{"sig":"MEUCIQDCT1hrVAlmtI82/RW4YhxFbrf8gIS7FXcpzDjD785P4QIgQY1osQKOmmA7XeyH9pptU0MAZVLY698s0rSQ5uMxam8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":310424},"main":"dist/index.js","type":"module","engines":{"node":">=18"},"gitHead":"378a24a6278d0213f2a3dbd1beb528aac9d0cf50","scripts":{"test":"node --test test/*.test.js","build":"tsc","pretest":"npm run build","dev:http":"tsc --watch --preserveWatchOutput & node --watch dist/http.js","start:http":"node dist/http.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"_npmVersion":"10.8.2","description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","express":"^5.2.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0","@types/express":"^5.0.6"},"_npmOperationalInternal":{"tmp":"tmp/flownest-mcp_0.7.0_1787440420664_0.7317809470922028","host":"s3://npm-registry-packages-npm-production"}},"0.7.1":{"name":"@berrylabs-id/flownest-mcp","version":"0.7.1","description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","type":"module","bin":{"flownest-mcp":"dist/index.js","flownest-mcp-http":"dist/http.js"},"main":"dist/index.js","engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc","start:http":"node dist/http.js","dev:http":"tsc --watch --preserveWatchOutput & node --watch dist/http.js","prepublishOnly":"npm run build","pretest":"npm run build","test":"node --test test/*.test.js"},"keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","express":"^5.2.1","zod":"^3.25.0"},"devDependencies":{"@types/express":"^5.0.6","@types/node":"^22.0.0","typescript":"^5.6.0"},"_id":"@berrylabs-id/flownest-mcp@0.7.1","gitHead":"9b5f5466bbfcca88bff3a555043cbbb39b30a915","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-vD5yN5DYiog6kUnL7LtbqcV//sK2qzCoCdBp9Z0tiXXP2jmPfwkYmGHPkJTghUFYCJezb3npgOVsIeddq1BfXA==","shasum":"475643dc0e766617e10c9786fc863326be1d0aec","tarball":"https://registry.npmjs.org/@berrylabs-id/flownest-mcp/-/flownest-mcp-0.7.1.tgz","fileCount":18,"unpackedSize":311660,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCx/kef3xvew51t1paiPQaQYBXeA8G9bNaC3Gg1R44JpwIhAJmWPuFAgk0k/mzUaR6T4BckwSAml9XSHp71dFEo4BFB"}]},"_npmUser":{"name":"berrylabs-id","email":"klosing.id@gmail.com"},"directories":{},"maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/flownest-mcp_0.7.1_1787443666379_0.6436704754898526"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-23T05:07:30.945Z","modified":"2026-08-23T00:07:46.696Z","0.1.0":"2026-06-23T05:07:31.199Z","0.1.1":"2026-06-23T06:46:50.506Z","0.2.0":"2026-06-23T08:41:28.941Z","0.3.0":"2026-07-22T10:11:07.193Z","0.5.0":"2026-08-22T12:09:40.069Z","0.6.0":"2026-08-22T13:27:35.097Z","0.7.0":"2026-08-22T23:13:40.812Z","0.7.1":"2026-08-23T00:07:46.544Z"},"license":"MIT","keywords":["mcp","model-context-protocol","flownest","claude-code","project-management","oauth"],"description":"MCP server for FlowNest. Drive FlowNest (tasks, comments, cycles, branches) from Claude Code, Claude Desktop, claude.ai web, or any MCP client via a Personal Access Token - locally over stdio, or hosted over Streamable HTTP with OAuth 2.1.","maintainers":[{"name":"berrylabs-id","email":"klosing.id@gmail.com"}],"readme":"# @berrylabs-id/flownest-mcp\n\nA local [Model Context Protocol](https://modelcontextprotocol.io) server that lets you drive FlowNest from any MCP-compatible AI client. Pull your tasks, read a task and its suggested git branch, update status, reply in comments, and see what changed - all without opening the FlowNest UI.\n\n## What It Is\n\nThis is a thin adapter: it holds no business logic and no secrets beyond the token you provide. Every action runs as you, through FlowNest's existing permission system. A tool that your FlowNest role forbids will fail with a clear `permission_denied` or `pro_required` error. Works locally, no extra server needed. Runs on any machine with Node.js.\n\n## Prerequisites\n\n- Node.js >= 18\n- A FlowNest account (https://flownest.id) on a **Pro** workspace\n\nYou do **not** need to create a token by hand. `flownest-mcp login` gets one for you.\n\nPro is not optional here: Personal Access Tokens are Pro-gated, and `login` mints\none. On a Free workspace the consent screen shows an upgrade prompt **in the\nbrowser** and never returns to the terminal, so the command waits until it times\nout. If `login` seems to hang, look at the tab it opened.\n\n## Quick Start\n\nSign in once:\n\n```bash\nnpx -y @berrylabs-id/flownest-mcp login\n```\n\nYour browser opens, you approve the connection, and a token is written to\n`~/.flownest/credentials` with owner-only permissions. Every MCP client on this\nmachine picks it up automatically, so the config carries no secret:\n\n```json\n{\n  \"mcpServers\": {\n    \"flownest\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@berrylabs-id/flownest-mcp\"]\n    }\n  }\n}\n```\n\nCheck it worked, or find out which credential is in play, with:\n\n```bash\nnpx -y @berrylabs-id/flownest-mcp status\n```\n\n### Why not paste a token into the config?\n\nYou still can, and for CI you should (see below). But on a workstation, a token\nin an MCP client config is a plaintext credential in a file that gets backed up,\nsynced and screen-shared, and FlowNest PATs do not expire. `login` keeps one copy\nin one place you can point at.\n\n`login` goes through the same consent screen as the hosted server at\n`mcp.flownest.id`, and issues the same kind of PAT. It appears in\nFlowNest > Settings > MCP and is revoked there.\n\n### CI, containers, and anything scripted\n\nSet `FLOWNEST_TOKEN`. It always **wins** over a stored login, so a credentials\nfile left on a shared build machine can never quietly take over:\n\n```bash\nFLOWNEST_TOKEN=fnp_xxx npx -y @berrylabs-id/flownest-mcp\n```\n\n### Commands\n\n| Command | What it does |\n|---|---|\n| `flownest-mcp` | Run the MCP server on stdio. This is what an MCP client does. |\n| `flownest-mcp login` | Browser sign-in. `--no-browser` prints the URL instead of launching one (for SSH and containers). |\n| `flownest-mcp logout` | Forget the stored token for this API. Does **not** revoke it server-side. |\n| `flownest-mcp status` | Show which token is in use, where it came from, and whether it still works. |\n\n## Setup by Client\n\n### Claude Code\n\nTwo lines in your terminal:\n\n```bash\nnpx -y @berrylabs-id/flownest-mcp login\nclaude mcp add flownest -- npx -y @berrylabs-id/flownest-mcp\n```\n\nThat is it. Claude Code will spawn the server on demand and FlowNest tools become available.\n\nPrefer to pass the token explicitly? That still works:\n\n```bash\nclaude mcp add flownest --env FLOWNEST_TOKEN=fnp_your_token_here -- npx -y @berrylabs-id/flownest-mcp\n```\n\n> The client blocks below all show an explicit `env` token, which still works.\n> If you have run `flownest-mcp login`, **drop the `env` line entirely** - the\n> server finds the stored credential on its own.\n\n### Claude Desktop\n\n1. Open Settings > Developer > Edit Config\n2. Locate the `mcpServers` section (or create it)\n3. Add this block:\n\n```json\n{\n  \"mcpServers\": {\n    \"flownest\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@berrylabs-id/flownest-mcp\"],\n      \"env\": { \"FLOWNEST_TOKEN\": \"fnp_your_token_here\" }\n    }\n  }\n}\n```\n\nConfig file locations:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nRestart Claude Desktop to load the MCP server.\n\n### Cursor\n\n**Option 1: GUI**\n1. Open Settings > MCP > Add\n2. Paste the Quick Start JSON config\n\n**Option 2: Manual config**\n1. Open or create `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local)\n2. Add the Quick Start JSON config\n3. Restart Cursor\n\n### VS Code (GitHub Copilot, agent mode)\n\n**Option 1: CLI**\n```bash\ncode --add-mcp '{\"name\":\"flownest\",\"command\":\"npx\",\"args\":[\"-y\",\"@berrylabs-id/flownest-mcp\"],\"env\":{\"FLOWNEST_TOKEN\":\"fnp_your_token_here\"}}'\n```\n\n**Option 2: Manual config**\n1. Open or create `.vscode/mcp.json` in your workspace\n2. Add the Quick Start JSON config\n3. Reload VS Code\n\n### Windsurf\n\n1. Open or create `~/.codeium/windsurf/mcp_config.json`\n2. Add the Quick Start JSON config:\n\n```json\n{\n  \"mcpServers\": {\n    \"flownest\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@berrylabs-id/flownest-mcp\"],\n      \"env\": { \"FLOWNEST_TOKEN\": \"fnp_your_token_here\" }\n    }\n  }\n}\n```\n\nRestart Windsurf.\n\n### Cline (VS Code extension)\n\n1. Open Cline settings in VS Code\n2. Find MCP Servers configuration\n3. Click Configure and add the Quick Start JSON config\n4. Restart VS Code\n\n### Gemini CLI\n\n1. Open or create `~/.gemini/settings.json`\n2. Add this block:\n\n```json\n{\n  \"mcpServers\": {\n    \"flownest\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@berrylabs-id/flownest-mcp\"],\n      \"env\": { \"FLOWNEST_TOKEN\": \"fnp_your_token_here\" }\n    }\n  }\n}\n```\n\n### claude.ai (web)\n\nclaude.ai's web app only supports connecting MCP servers via OAuth - there is no field for pasting a raw token. Use the hosted server instead of the npm package:\n\n1. claude.ai -> **Settings -> Connectors -> Add custom connector**.\n2. Paste `https://mcp.flownest.id/mcp` and confirm.\n3. Click **Authorize** - you will be redirected to log in to FlowNest (if not already) and then to a consent screen showing the requesting app and your account.\n4. Click **Allow** - claude.ai receives an access token that **is** a Personal Access Token, so it shows up (and can be revoked) in **Settings > MCP** like any other token.\n\nNo refresh token is issued - PATs do not expire, so there is nothing to refresh; revoke from Settings instead.\n\n## Configuration\n\nTwo entrypoints, two configs. Local stdio (`dist/index.js`, the default `flownest-mcp` bin, what every client config above uses) needs a credential, from either `login` or the environment:\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `FLOWNEST_TOKEN` | no, once you have run `login` | - | Your Personal Access Token (starts with `fnp_`). **Takes precedence** over a stored login. Without either, the server exits with an error naming both options. |\n| `FLOWNEST_API_URL` | no | `https://api.flownest.id` | Override only for self-hosted or staging environments. Credentials are stored per API URL, so a local login never shadows a production one. |\n| `FLOWNEST_MCP_URL` | no | `https://mcp.flownest.id` | The authorization server `login` signs in against. |\n| `FLOWNEST_CONFIG_DIR` | no | `~/.flownest` | Where the credentials file lives. |\n\nNote that the credentials file is a plaintext token on disk, written `0600` in a\n`0700` directory. That is not stronger than an environment variable in any\ncryptographic sense; what it buys you is one copy in one known place instead of\nhowever many places a token gets pasted, and `logout` to remove it. Since\nFlowNest PATs do not expire, revoke a token you think has leaked from\nFlowNest > Settings > MCP - `logout` only forgets it locally.\n\n### Hosted HTTP + OAuth 2.1 (`dist/http.js`, operators only)\n\nA second entrypoint (`flownest-mcp-http` bin, `npm run start:http`) that serves the same tools (registered from the same `tools.ts` as the stdio entrypoint - 65 as of this writing) over Streamable HTTP and doubles as an OAuth 2.1 authorization server, so claude.ai web (and any other Streamable-HTTP + OAuth 2.1 client) can connect without a locally-configured token. This is what runs behind `https://mcp.flownest.id`. See docs/superpowers/specs/2026-07-22-hosted-mcp-oauth-design.md for the full design.\n\nArchitecture: a thin adapter, same as the stdio entrypoint - no business logic, no database. `src/http.ts` builds a fresh `McpServer` + `FlowNestClient` + `StreamableHTTPServerTransport` **per request**, scoped to that request's bearer token; nothing is retained between requests. The access token minted by the OAuth flow **is** an ordinary PAT (`fnp_...`) - it appears in Settings > MCP and is revoked there, exactly like a manually-created token. There is no second token-management surface and no refresh token (PATs do not expire).\n\n| Env var | Required | Default | Notes |\n|---|---|---|---|\n| `PORT` | no | `8100` | HTTP port. |\n| `HOST` | no | `0.0.0.0` | Bind address. |\n| `FLOWNEST_API_URL` | no | `https://api.flownest.id` | Point at `http://localhost:7777` for local testing against a local `flownest-api`. Also where OAuth code exchange is forwarded (`POST {FLOWNEST_API_URL}/v1/public/mcp-oauth/exchange`). |\n| `MCP_ALLOWED_HOSTS` | no | `localhost,127.0.0.1,[::1]` | Comma-separated hostnames (no scheme/port) accepted in the incoming `Host` header - the SDK's built-in DNS-rebinding protection. **Prod must set this to the public hostname**, e.g. `mcp.flownest.id`. |\n| `PUBLIC_URL` | no | `https://mcp.flownest.id` | This server's own public URL - used as the OAuth issuer and protected-resource identifier (`{PUBLIC_URL}/mcp`). Point at `http://localhost:8100` for local testing. |\n| `APP_URL` | no | `https://flownest.id` | The FlowNest app's public URL - where `/authorize` redirects the user for consent (`{APP_URL}/connect/mcp`). |\n| `MCP_OAUTH_SIGNING_KEY` | **yes** | *(none)* | Base64-encoded 32-byte HMAC key that signs Dynamic Client Registration `client_id`s and the consent payload handed to the FlowNest app. **MUST be byte-identical to `flownest-api`'s copy of the same env var** - both sides sign/verify the same blobs. Generate with `openssl rand -base64 32`. The server refuses to start without it. |\n\nEndpoints:\n\n- `GET /healthz` - 200, no auth.\n- `POST /mcp` - the MCP endpoint. Requires `Authorization: Bearer fnp_...`; a missing/malformed header returns a spec-correct `401` with `WWW-Authenticate: Bearer ... resource_metadata=\"...\"` (via the SDK's `requireBearerAuth`) so OAuth-aware clients (claude.ai) know where to authorize.\n- `GET /mcp`, `DELETE /mcp` - `405` (this server is stateless: no session to resume or terminate).\n- `GET /.well-known/oauth-authorization-server` - OAuth 2.1 / RFC 8414 authorization server metadata.\n- `GET /.well-known/oauth-protected-resource/mcp` - RFC 9728 protected resource metadata for `/mcp`.\n- `POST /register` - Dynamic Client Registration (RFC 7591). Public clients only (`token_endpoint_auth_method: \"none\"`) - see `src/oauth/clients.ts`.\n- `GET|POST /authorize` - starts the OAuth flow; redirects to `{APP_URL}/connect/mcp?payload=...`.\n- `POST /token` - exchanges an authorization code for an `fnp_...` access token.\n\nRun locally:\n\n```bash\nnpm run build\nMCP_OAUTH_SIGNING_KEY=... FLOWNEST_API_URL=http://localhost:7777 PUBLIC_URL=http://localhost:8100 APP_URL=http://localhost:2222 npm run start:http\n```\n\n## Tools\n\nAny tool that takes a `task` argument accepts either a UUID or a human display code (e.g. `OEX-12` or dotted subtask code like `OEX-1.1`). Status and label targets accept either an ID or a human name (e.g. `\"In Progress\"`, `\"bug\"`), resolved against the project; an unknown name fails with the available names listed. Project, cycle, and assignee targets use IDs - discover them with the `list_*` tools.\n\n**`workspace` is required on every tool that takes it.** It used to be optional wherever a `task` was also given, on the assumption that the workspace could be inferred from the code. It cannot: task codes are not unique across workspaces, and the server treats `workspace_id` on the code resolver as a sort preference rather than a filter. Calling `create_subtask` with `parent_task: \"PRO-1\"` and no workspace once wrote seven subtasks into an unrelated workspace, under a stranger's task that happened to share the code, and every call returned success. Now the workspace must be named, and a reference that resolves somewhere else is refused with `task_in_other_workspace` instead of being written to.\n\nGet the id from `get_my_context`. Never reuse one from an unrelated request.\n\nEvery action is limited by your own FlowNest permissions.\n\n### Start here\n\n| Tool | What it does |\n|---|---|\n| `get_my_context` | **Call this first in a new session.** The only tool that takes no arguments. Returns who you are and every workspace you belong to (id, name, your role, plan), so nothing else has to ask a human for a workspace UUID. |\n\n### Read\n\n| Tool | What it does |\n|---|---|\n| `list_my_tasks` | Your assigned tasks across all workspaces, grouped by overdue / upcoming / no-date. Optional `status` filter. Also returns `assigned_comments`: comments assigned to you as lightweight actionable items. |\n| `get_task` | Full task details by UUID or code. |\n| `list_projects` | Projects (lists) in a workspace, to map a project name to its ID. |\n| `list_cycles` | Cycle groups and their cycles (sprints) in a workspace. |\n| `list_docs` | Docs (pages) in a workspace as light summaries (id, title, project_id). Bodies are not included. |\n| `list_workspace_members` | Workspace members (ID, name, email, role), to map a person to a user ID. |\n| `get_my_updates` | A digest of what changed on your tasks since a timestamp (new comments, reassignments, status changes, comment assignments). |\n| `get_task_comments` | The comment thread on a task. |\n| `get_task_activity` | The activity feed for a task. |\n| `get_task_branch` | The suggested git branch name and base for a task (you create the branch locally). |\n| `search` | Search a workspace across tasks, comments, docs, projects and members, grouped by kind. |\n| `list_project_statuses` | The statuses defined on a project, to map a status name to its ID. |\n| `list_labels` | The labels defined on a project, to map a label name to its ID. |\n| `list_teams` | Teams in a workspace. |\n| `list_my_teams` | The teams you belong to. |\n| `list_team_members` | Members of a team. |\n| `get_task_checklist` | The checklist items on a task. |\n| `get_task_dependencies` | What a task blocks and what blocks it. |\n| `list_templates` | Task, project and status-set templates in a workspace. |\n| `list_automations` | The When/If/Then rules on a project. |\n| `list_automation_runs` | Recent runs of an automation, so you can see why a rule did or did not fire. |\n| `get_performance_report` | Completed work, on-time rate and cycle time per member, by workspace, team, cycle or yourself. |\n| `get_workload_report` | Active load per member for a team or project, plus unassigned work. |\n\n### Write\n\n| Tool | What it does |\n|---|---|\n| `create_task` | Create a task in a project (can set parent, assignees, story point, estimate, cycle in one call). Also matches it against the System Map and reports the result as `design_link` - including a warning when the task corresponds to nothing in the design, which means the work is outside the plan or the plan has a hole. Pass `link_to_design: \"auto\"` to draw the edge when one match is clearly ahead, or `implements` to name the node yourself. |\n| `create_subtask` | Create a subtask under a parent task (defaults to parent's project). |\n| `update_task` | Update title, description, priority, status, dates, story point, time estimate. |\n| `delete_task` | Delete a task and its subtasks. Destructive and not undoable here - it exists so a task created in the wrong place can be taken back without opening the web app. Confirm the target with `get_task` first. |\n| `update_task_status` | Move a task to a status by status ID or status name (e.g. \"In Progress\"). |\n| `assign_task` | Set a task's assignees (replace-set; empty array unassigns). |\n| `create_cycle` | Create a cycle/sprint in a workspace (default Sprints group, or pass a cycle group id). Optional start and end dates. |\n| `create_cycle_group` | Create a cycle group (a track that holds sprints) in a workspace. |\n| `add_task_to_cycle` | Add a task to a cycle/sprint. |\n| `remove_task_from_cycle` | Remove a task from a cycle/sprint. |\n| `add_task_to_list` | Add a task to a secondary project/list (\"Other Lists\"). |\n| `remove_task_from_list` | Remove a task from a secondary list. |\n| `set_task_home` | Move a task's home (primary) project. The display code stays the same. |\n| `add_comment` | Post a comment on a task. |\n| `assign_comment` | Assign a comment to a workspace member (Assigned Comments) - a lightweight actionable item without creating a subtask. Pass `assignee_id: null` to unassign. |\n| `resolve_comment` | Mark an assigned comment resolved (idempotent). Clears it from the assignee's My Tasks. |\n| `create_doc` | Create a doc (page), optionally with a title, HTML body, and a project to file it under. |\n| `create_artifact` | Store a self-contained HTML page (a design brief) beside Docs. Use this instead of `create_doc` when the page has its own styling, layout, or inline SVG - a doc body is rich text and strips all of that. Renders sandboxed on a separate hostname, so its scripts cannot reach FlowNest or the reader's session. |\n| `list_artifacts` | The HTML artifacts in a workspace (id, title, size), newest first. Metadata only, never the body. |\n| `delete_artifact` | Delete an artifact and its stored file. Destructive and not undoable here; any public share link stops working immediately. Confirm the target with `list_artifacts` first. |\n| `add_doc_to_project` | File a doc under a project/list (sets the doc's project link). |\n| `add_checklist_item` | Add an item to a task's checklist. |\n| `update_checklist_item` | Tick, untick or rename a checklist item. |\n| `add_task_dependency` | Record that one task blocks another. |\n| `request_approval` | Ask named workspace members to sign off on a task. A task cannot reach a done status until they do. |\n| `decide_approval` | Approve or reject a sign-off request you were named on. |\n| `instantiate_template` | Create a task, project or status set from a template, substituting its variables. |\n| `create_automation` | Create a When/If/Then rule on a project: when a trigger fires, if the conditions match, then run the actions. |\n| `update_automation` | Change a rule, including enabling or disabling it. |\n\n### Test cases\n\nA project-scoped test library, run against tasks: author test cases (precondition, steps, expected result) and optionally link one to a task in the same call; link or unlink an existing test case to/from a task; record a pass/fail/blocked result against a (test case, task) pair, optionally pointing at a defect task; update or archive a test case (archiving never deletes - the full execution history survives); list a workspace's or one project's library; and pull a task's whole test panel (every linked test, its latest result, and a progress summary) in one call. 8 tools, starting with `create_test_case` and `get_task_tests`.\n\n### AI Skill Modules\n\n| Tool | What it does |\n|---|---|\n| `use_skill` | Load an expert methodology into your own context before starting that kind of work (currently: `test-case-writing`, a senior-QA test design method). A local lookup, not a FlowNest API call - works even on a Free workspace. |\n| `read_doc` | Fetch a doc's (wiki page) full detail by ID: title, project link, and body. Use `list_docs` to find a doc's ID first. |\n| `draft_test_cases` | Batch-create 1-100 test cases in a project, optionally linking every one to a task. The write half of the test-case-writing skill. Pro-only; requires `confirmed: true`, set only after the drafted cases have been shown to and approved by the user. |\n\n3 tools, starting with `use_skill`.\n\n## Security\n\n- Every action runs as you, limited by your own FlowNest role. The token carries no extra power.\n- The token is read from the environment only. The server stores nothing and keeps no state.\n- A token can be revoked at any time from FlowNest > Settings > MCP; revoking stops all access immediately.\n- A token cannot create or manage other tokens (only a real web session can).\n- FlowNest stores the token as a SHA256 hash, never in plaintext.\n\n## Troubleshooting\n\n**`pro_required` error**\n- Token creation requires a Pro workspace. Upgrade at FlowNest > Settings > Billing.\n\n**`unauthorized` or 401 error**\n- Your token has been revoked, expired, or is incorrect.\n- Create a new one at FlowNest > Settings > MCP.\n\n**`command not found` right after install**\n- Your npx cache is stale.\n- Run `rm -rf ~/.npm/_npx` and try again.\n\n## Development\n\n```bash\nnpm install\nnpm run build      # tsc -> dist/\nFLOWNEST_TOKEN=fnp_xxx node dist/index.js   # run the stdio server directly\nnode dist/index.js --version\n```\n\n## Links\n\n- FlowNest: https://flownest.id\n- MCP Setup Guide: https://flownest.id/docs/mcp\n\n## License\n\nMIT\n","readmeFilename":"README.md"}