{"id":51310845,"url":"https://github.com/cmdaltctr/niftypm-mcp","last_synced_at":"2026-07-01T04:00:33.058Z","repository":{"id":363566083,"uuid":"1263224448","full_name":"cmdaltctr/niftypm-mcp","owner":"cmdaltctr","description":"A Model Context Protocol (MCP) server that exposes the NiftyPM project management API as a set of tools for AI assistants (OpenCode, Claude, Cursor, etc.).","archived":false,"fork":false,"pushed_at":"2026-06-09T11:48:28.000Z","size":201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T13:22:37.577Z","etag":null,"topics":["api","claude","claude-code","mcp","niftypm","opencode"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmdaltctr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T18:40:40.000Z","updated_at":"2026-06-09T11:48:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cmdaltctr/niftypm-mcp","commit_stats":null,"previous_names":["cmdaltctr/niftypm-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cmdaltctr/niftypm-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdaltctr%2Fniftypm-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdaltctr%2Fniftypm-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdaltctr%2Fniftypm-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdaltctr%2Fniftypm-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmdaltctr","download_url":"https://codeload.github.com/cmdaltctr/niftypm-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmdaltctr%2Fniftypm-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34992071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","claude","claude-code","mcp","niftypm","opencode"],"created_at":"2026-07-01T04:00:22.388Z","updated_at":"2026-07-01T04:00:33.031Z","avatar_url":"https://github.com/cmdaltctr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NiftyPM MCP Server\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [NiftyPM](https://niftypm.com) project management API.\n\nIt lets AI assistants use NiftyPM projects, tasks, documents, files, milestones, messages, labels, portfolios, webhooks, time tracking, custom fields, checklists, and related workspace resources through typed MCP tools.\n\n## Highlights\n\n- Local `stdio` server for desktop MCP clients.\n- CLI subcommands: `init` (bootstrap local JSON), `sync` (re-sync from API), direct tool invocation.\n- Local auto-sync: automatically updates `niftypm/*.json` files after mutations.\n- Optional HTTP stream transport for local testing.\n- Cloudflare Workers entry point for hosted/remote use.\n- OAuth bearer-token API client with in-memory token refresh on `401`.\n- Zod-validated tool parameters.\n- Per-domain tool toggles through `ENABLE_*` environment variables, plus\n  per-tool granularity via `DISABLED_TOOLS`.\n\n## Requirements\n\n- Node.js 20+\n- Bun 1.1+\n- NiftyPM OAuth credentials:\n  - `NIFTYPM_CLIENT_ID`\n  - `NIFTYPM_CLIENT_SECRET`\n  - `NIFTYPM_ACCESS_TOKEN`\n  - `NIFTYPM_REFRESH_TOKEN`\n\n## Install\n\n```bash\ngit clone https://github.com/cmdaltctr/niftypm-mcp.git\ncd niftypm-mcp\nbun install\n```\n\n## Configure\n\n### Configurator UI\n\nThe easiest setup path is the static configurator at [`ui/index.html`](ui/index.html):\n\n1. Open `ui/index.html` directly in a browser.\n2. Paste your OAuth credentials.\n3. Switch between **Simple** (domain-level toggles) and **Advanced** (per-tool toggle table) tabs.\n4. Click **Download `.env`**.\n5. Rename it to `.env`, place it in the project root, and restart your MCP client.\n\nThe configurator runs entirely in your browser. It makes no network requests and does not send secrets anywhere.\n\nThe **Simple** tab shows 21 domain-level switches (core + extended + checklists). The\n**Advanced** tab gives you per-tool control — disable individual tools\nwithin an enabled domain, down to a single unwanted operation. The\ngenerated `.env` is auto-loaded on server start.\n\n### Manual `.env` setup\n\nYou can also copy the example env file and fill in your OAuth credentials by hand:\n\n```bash\ncp .env.example .env\n```\n\n```dotenv\nNIFTYPM_CLIENT_ID=your_client_id_here\nNIFTYPM_CLIENT_SECRET=your_client_secret_here\nNIFTYPM_ACCESS_TOKEN=your_access_token_here\nNIFTYPM_REFRESH_TOKEN=your_refresh_token_here\n```\n\n`NIFTYPM_REFRESH_TOKEN` is the OAuth refresh token for automatic `401` recovery. It is required for stable connections — without it, every access-token expiry forces manual re-authorisation.\n\n### How to obtain the refresh token\n\nUse NiftyPM's OAuth authorisation-code flow:\n\n1. Create or use a NiftyPM OAuth app and note its client ID, client secret, and redirect URI.\n2. Open the app's authorisation URL in a browser and approve access.\n3. Copy the `code` value from the callback URL sent to your redirect URI.\n4. Exchange that code for tokens with `POST https://openapi.niftypm.com/oauth/token`.\n\nExample token exchange:\n\n```bash\ncurl -X POST https://openapi.niftypm.com/oauth/token \\\n  -H \"Authorization: Basic $(printf '%s:%s' \"$NIFTYPM_CLIENT_ID\" \"$NIFTYPM_CLIENT_SECRET\" | base64)\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"grant_type\": \"authorization_code\",\n    \"code\": \"AUTHORIZATION_CODE_FROM_CALLBACK\",\n    \"redirect_uri\": \"YOUR_REDIRECT_URI\"\n  }'\n```\n\nThe response includes both `access_token` and `refresh_token`. Store them as `NIFTYPM_ACCESS_TOKEN` and `NIFTYPM_REFRESH_TOKEN`.\n\n### Manual `.secrets/` option\n\nFor OpenCode or local setups, you may store credentials in `.secrets/` files instead of `.env`:\n\n```text\n.secrets/client_id\n.secrets/client_secret\n.secrets/access_token\n.secrets/refresh_token\n.secrets/team_token       (optional — needed for checklist write operations)\n```\n\n### Checklist setup (optional)\n\nChecklist tools use NiftyPM's internal API (`api.niftypm.com`) which requires a **team token** — a separate credential from the OAuth access token. Without it, checklist reads work but writes (create/update/delete) return 401.\n\nTo obtain the team token:\n\n1. Log into your NiftyPM workspace in a browser.\n2. Open DevTools Console (F12 → Console).\n3. Run this one-liner:\n   ```javascript\n   JSON.parse(decodeURIComponent(document.cookie.match(/nifty_auth=([^;]+)/)[1])).teamToken;\n   ```\n4. Save the output using one of these methods:\n\n   **Option A — `.secrets/` file** (recommended for local/OpenCode setups):\n\n   ```bash\n   echo \"PASTE_TOKEN_HERE\" \u003e .secrets/team_token\n   ```\n\n   **Option B — `.env` or environment variable:**\n\n   ```bash\n   # In .env:\n   NIFTYPM_TEAM_TOKEN=PASTE_TOKEN_HERE\n   ```\n\nThe team token has a long expiry (months). If checklist operations start returning 401, repeat the extraction.\n\nThe UI configurator remains the easiest path because it generates a complete `.env` by copy-paste and download. See [Configuration and Deployment](docs/guides/configuration.md) for more deployment details.\n\n## Run locally\n\n```bash\nbun run start\n```\n\nWatch mode:\n\n```bash\nbun run dev\n```\n\nHTTP stream mode:\n\n```bash\nTRANSPORT=http PORT=8080 bun run start\n```\n\n## Deploy to Cloudflare Workers\n\n```bash\nbun run cf:dev\nbun run cf:deploy\n```\n\nWorker access is protected by `MCP_AUTH_SECRET`. Store production values with `wrangler secret put`.\n\n## Tool domains\n\nThe server groups tools by NiftyPM resource domain:\n\n- Projects, portfolios/subteams, members\n- Task groups, tasks, subtasks, labels, custom fields\n- Checklists and checklist items (requires team token — see [Checklist setup](#checklist-setup-optional))\n- Documents, files, messages, chat\n- Milestones, time tracking, webhooks\n- Apps, templates, invite links, current user, auth helpers\n\nFor detailed tool names and examples, see [Tool Guide](docs/guides/tools.md).\n\n## Project Planning Workflow\n\nThe most effective way to populate complex projects is using a **JSON-first planning workflow**. Instead of making ad-hoc tool calls, define your project structure (milestones, labels, tasks, dependencies) in a JSON file first. This serves as the source of truth, allowing you to validate relationships and ensure tasks have required fields (like story points and real subtasks) before making any API calls to NiftyPM.\n\nFor details on executing this four-phase pipeline, see the [Workflow Guide](docs/guides/workflow.md).\n\n## AI Agent Skills\n\nThe `SKILLS/` folder contains drop-in agent skill instructions that teach AI coding assistants (Claude Code, OpenCode, Cursor, etc.) how to use this MCP server effectively — including the JSON-first project planning workflow, the four-phase execution pipeline, and NiftyPM best practices.\n\nCopy the `SKILLS/s-niftypm/` folder to the appropriate location for your AI client:\n\n| AI Client       | Destination path                                           |\n| --------------- | ---------------------------------------------------------- |\n| **Claude Code** | `~/.claude/skills/s-niftypm/`                              |\n| **OpenCode**    | `~/.config/opencode/skills/s-niftypm/`                     |\n| **Cursor**      | `~/.cursor/rules/` (then wrap `SKILL.md` in a `.mdc` rule) |\n| **Other**       | Check your client's docs for a skills/rules directory      |\n\nExample (Claude Code / OpenCode):\n\n```bash\n# From inside the cloned repo\ncp -r SKILLS/s-niftypm ~/.claude/skills/\n# or for OpenCode\ncp -r SKILLS/s-niftypm ~/.config/opencode/skills/\n```\n\nOnce installed, your AI agent will automatically load the `s-niftypm` skill when working with NiftyPM MCP tools and follow the JSON-first planning workflow by default.\n\n## Example tool calls\n\nCreate a task:\n\n```json\n{\n  \"tool\": \"niftypm_create_task\",\n  \"arguments\": {\n    \"name\": \"Prepare fellowship report\",\n    \"task_group_id\": \"task_group_id_here\",\n    \"description\": \"Draft the report outline.\"\n  }\n}\n```\n\nCreate a related subtask by passing the parent task ID as `task_id`:\n\n```json\n{\n  \"tool\": \"niftypm_create_task\",\n  \"arguments\": {\n    \"name\": \"Collect reviewer feedback\",\n    \"task_group_id\": \"task_group_id_here\",\n    \"task_id\": \"parent_task_id_here\"\n  }\n}\n```\n\n## CLI Usage\n\nThe `niftypm-mcp` binary supports CLI subcommands in addition to starting the MCP server. This is useful for bootstrapping local project JSON files, re-syncing from the live API, and calling tools directly from the command line.\n\n### `niftypm-mcp init`\n\nInteractive wizard that lists all accessible NiftyPM projects, lets you select one, fetches all entities, and writes a structured JSON file to `niftypm/\u003cproject-name\u003e.json` in the current working directory.\n\n```bash\ncd /path/to/your/project\nniftypm-mcp init\n```\n\n### `niftypm-mcp sync`\n\nRe-syncs an existing local JSON file from the live NiftyPM API. Reads `meta.niftypm_project_id` from the local file, fetches all entities, and rewrites the file with fresh data.\n\n```bash\ncd /path/to/your/project\nniftypm-mcp sync\n```\n\n### Direct tool invocation\n\nAny registered MCP tool can be called directly from the CLI. Arguments are parsed as `--key value` pairs:\n\n```bash\nniftypm-mcp niftypm_list_tasks --project_id \"abc123\"\nniftypm-mcp niftypm_create_task --name \"Fix bug\" --task_group_id \"abc123\"\nniftypm-mcp niftypm_list_tasks --project_id \"abc123\" --completed\n```\n\n- Repeated flags produce arrays: `--label lab1 --label lab2`\n- Boolean flags: `--completed` (true), `--no-archived` (false)\n\n### Local auto-sync\n\nWhen the MCP server starts in `stdio` mode, it scans `niftypm/*.json` in the current working directory. If local JSON files are found, the server automatically updates the affected section after every mutation (POST/PUT/DELETE). This provides an offline backup that stays in sync with live NiftyPM data.\n\n- **No configuration needed** — just run `niftypm-mcp init` in your project directory.\n- **Targeted refetch** — only the affected entity type is re-fetched, not the entire project.\n- **Atomic writes** — files are written to a temp file then renamed to prevent corruption.\n- **Silent disable** — if no `niftypm/` directory or JSON files are found, auto-sync is silently disabled.\n- **Workers-safe** — auto-sync is only active in Node.js stdio mode, never in Cloudflare Workers.\n\n## Documentation\n\n- [CLI Guide](docs/guides/cli.md)\n- [Configuration and Deployment](docs/guides/configuration.md)\n- [Tool Guide](docs/guides/tools.md)\n- [API Coverage](docs/guides/api-coverage.md)\n- [Migration Guide](docs/guides/migration.md)\n- [Workflow Guide](docs/guides/workflow.md)\n\n## Development\n\n```bash\nbun run vitest run\nbun run build\n```\n\n## Project layout\n\n```text\nsrc/              MCP server, API client, and tool registrations\ntest/             Vitest tests\ndocs/guides/      User-facing guides and reference docs\ndocs/api/         Upstream OpenAPI source files\ndocs/security/    Security audit notes\n```\n\n## Licence\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdaltctr%2Fniftypm-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmdaltctr%2Fniftypm-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmdaltctr%2Fniftypm-mcp/lists"}