@theyahia/megaplan-mcp 3.0.0 → 4.0.0

package/LICENSE

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

package/README.md

@@ -1,68 +1,64 @@
 # @theyahia/megaplan-mcp
 
-> MCP server for **Megaplan** project management — tasks, deals, projects, employees, comments via API v3.
-> 8 tools + 2 MCP prompts. Token OR Password-grant auth. Stdio + Streamable HTTP transports.
+MCP server for **Megaplan** project management. Tasks, deals, projects,
+employees, clients, and comments via Megaplan API v3.
 
-[![npm](https://img.shields.io/npm/v/@theyahia/megaplan-mcp)](https://www.npmjs.com/package/@theyahia/megaplan-mcp)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+> **v4.0 is a breaking release** (and the first npm release of this overhaul —
+> it supersedes the older 8-tool `3.0.0`). Request/response shapes changed to
+> match the real v3 API, and `--http` now requires an auth token. See
+> [CHANGELOG.md](./CHANGELOG.md) and [Migrating from older versions](#migrating-from-older-versions).
 
----
-
-### Migrating from v1.x
-
-If you used v1.x, the v2.0.0 release introduces a few breaking changes:
-
-- **HTTP transport env var renamed:** `PORT=3000` → `HTTP_PORT=3000`.
-- **Removed separate `--http` codepath:** v1 had a hand-rolled `http.ts` triggered by `--http`. v2 uses `@theyahia/mcp-core`'s `runServer` which auto-routes via `--http` flag OR `HTTP_PORT` env. Same CLI flag, different implementation (now with session management, `/health` endpoint, CORS, graceful shutdown).
-- **Internal client:** rewritten on `@theyahia/mcp-core`'s `BaseHttpClient` with a custom `MegaplanAuthStrategy` (Password grant flow). The exported `megaplanGet`/`megaplanPost` API is unchanged.
-- **Tool errors:** now returned as MCP-spec `CallToolResult` with `isError: true` (via `withErrorHandling`).
-
-Tool names, arguments, return formats, MCP prompts (`my-tasks-today`, `create-deal-wizard`), and `MEGAPLAN_*` env vars are unchanged.
-
----
-
-## Tools (8) + Prompts (2)
-
-### Tasks
+## Tools (18)
 
 | Tool | Description |
-|------|-------------|
-| `get_tasks` | List tasks with filters by status (active / completed / delayed), responsible user, search. |
-| `create_task` | Create a new task (name, description, responsible, deadline). |
-
-### Deals
-
-| Tool | Description |
-|------|-------------|
-| `get_deals` | List deals with filters by status, responsible user, search. |
-| `create_deal` | Create a new deal (name, pipeline, responsible, amount). |
-
-### Projects & Employees
-
-| Tool | Description |
-|------|-------------|
-| `get_projects` | List projects with filters by status and search. |
-| `get_employees` | List employees with search and department filter. |
-
-### Comments
+|------|------------|
+| `get_tasks` | List tasks; filter by status code(s), responsible, search |
+| `get_task` | Get one task by ID |
+| `create_task` | Create a task (name, description, responsible, deadline) |
+| `update_task` | Update a task (name, description, responsible, deadline, status) |
+| `get_deals` | List deals; filter by status code(s), responsible, search |
+| `get_deal` | Get one deal by ID |
+| `create_deal` | Create a deal (requires a program/pipeline ID) |
+| `update_deal` | Update a deal (name, responsible, amount, description, status) |
+| `get_projects` | List projects; filter by status code(s), search |
+| `get_project` | Get one project by ID |
+| `get_employees` | List employees; search + department filter |
+| `get_deal_programs` | List deal programs (pipelines) — find the `program_id` for `create_deal` |
+| `get_deal_program` | Get one deal program by ID |
+| `list_clients` | List clients (contractors): people (`human`) or orgs (`company`) |
+| `get_client` | Get one client by type + ID |
+| `get_current_user` | Authenticated user's employee record (**experimental**) |
+| `get_comments` | List comments on a task/deal/project |
+| `create_comment` | Add a comment to a task/deal/project |
+
+All list/get tools return a **compact summary** by default; pass `raw: true` for
+the unmodified API JSON. Lists are cursor-paginated: pass the returned
+`nextPageAfter` as `page_after` to get the next page.
+
+## Skills (Prompts)
+
+| Skill | Description |
+|-------|------------|
+| `my-tasks-today` | "Мои задачи на сегодня" — your tasks (scoped via `get_current_user`) |
+| `create-deal-wizard` | "Создай сделку" — guided deal creation (lists pipelines first) |
+
+## Setup
+
+### Option A: Access Token
 
-| Tool | Description |
-|------|-------------|
-| `get_comments` | List comments on a task / deal / project. |
-| `create_comment` | Add a comment to a task / deal / project. |
-
-### MCP Prompts
+1. In Megaplan, go to **Settings → Integration → API**.
+2. Generate an access token, and set it as `MEGAPLAN_TOKEN`.
 
-| Prompt | Description |
-|--------|-------------|
-| `my-tasks-today` | "Мои задачи на сегодня" — fetches your active tasks sorted by urgency, marks overdue. |
-| `create-deal-wizard` | "Создай сделку" — guided deal creation wizard via conversation. |
+### Option B: Login + Password
 
----
+Set `MEGAPLAN_LOGIN` (email) + `MEGAPLAN_PASSWORD`. The server exchanges them for
+an access token (cached in memory, re-authenticated on expiry).
 
-## Quick Start
+`MEGAPLAN_DOMAIN` is your account host. A bare subdomain like `yourcompany` is
+expanded to `yourcompany.megaplan.ru`; a full host (`crm.example.com`) is used
+as-is.
 
-### Claude Desktop — token auth
+## Usage with Claude Desktop
 
 ```json
 {
@@ -72,135 +68,101 @@ Tool names, arguments, return formats, MCP prompts (`my-tasks-today`, `create-de
       "args": ["-y", "@theyahia/megaplan-mcp"],
       "env": {
         "MEGAPLAN_DOMAIN": "yourcompany",
-        "MEGAPLAN_TOKEN": "your_access_token"
+        "MEGAPLAN_TOKEN": "your-access-token"
       }
     }
   }
 }
 ```
 
-### Claude Desktop — login/password auth
-
-```json
-{
-  "mcpServers": {
-    "megaplan": {
-      "command": "npx",
-      "args": ["-y", "@theyahia/megaplan-mcp"],
-      "env": {
-        "MEGAPLAN_DOMAIN": "yourcompany",
-        "MEGAPLAN_LOGIN": "user@example.com",
-        "MEGAPLAN_PASSWORD": "your_password"
-      }
-    }
-  }
-}
-```
+Or with login/password — replace `MEGAPLAN_TOKEN` with `MEGAPLAN_LOGIN` +
+`MEGAPLAN_PASSWORD`.
 
-### Cursor / Windsurf
+## Finding IDs
 
-Same configuration block under `mcpServers` in the IDE's MCP settings.
+Several tools take IDs. Here's how to discover them via the server itself:
 
-### VS Code (Copilot)
+- **`responsible_id`, `filter_responsible_id`** → `get_employees` (each item has an `id`).
+- **`filter_department_id`** → IDs appear on employees' `department` (or your Megaplan UI).
+- **`program_id`** (required by `create_deal`) → `get_deal_programs`.
+- **`contact_id`** (for `create_deal`) → `list_clients` with `type: "human"` or `"company"`; pass the matching `contact_type`.
+- **status codes** (`filter_status`) are account-specific enum codes (e.g. `filter_any`), not display names. Find them in your Megaplan UI / account API schema.
 
-Same shape under `.vscode/mcp.json` `servers` key.
+## Streamable HTTP transport
 
-### Streamable HTTP transport
+For remote/cloud deployments, run with `--http`. **Auth is mandatory** — the
+server holds your Megaplan credentials, so it refuses to start without
+`MCP_HTTP_TOKEN` and binds to loopback by default.
 
 ```bash
-HTTP_PORT=3000 \
 MEGAPLAN_DOMAIN=yourcompany \
-MEGAPLAN_TOKEN=your_token \
-npx @theyahia/megaplan-mcp
-# or: npx @theyahia/megaplan-mcp --http
+MEGAPLAN_TOKEN=xxx \
+MCP_HTTP_TOKEN=$(openssl rand -hex 32) \
+npx @theyahia/megaplan-mcp --http
+# → http://127.0.0.1:3000/mcp  (send: Authorization: Bearer $MCP_HTTP_TOKEN)
+# Health: http://127.0.0.1:3000/health
 ```
 
-Endpoints:
-- `POST /mcp` — MCP requests
-- `GET /mcp` — SSE event stream (per session)
-- `DELETE /mcp` — session termination
-- `GET /health` — `{ status: "ok", version, tools, uptime, memory_mb }`
-
----
+To expose beyond loopback, set `HOST=0.0.0.0` **and** add the public host:port to
+`MCP_HTTP_ALLOWED_HOSTS` (DNS-rebinding protection is on). Only do this behind
+your own network controls.
 
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `MEGAPLAN_DOMAIN` | yes | Your Megaplan subdomain (e.g. `mycompany` for `mycompany.megaplan.ru`). |
-| `MEGAPLAN_TOKEN` | one of | Bearer access token (preferred — no auth roundtrip). |
-| `MEGAPLAN_LOGIN` | one of | Login email (used with `MEGAPLAN_PASSWORD` if no token). |
-| `MEGAPLAN_PASSWORD` | one of | Password (used with `MEGAPLAN_LOGIN` if no token). |
-| `HTTP_PORT` | no | If set, server runs in HTTP mode on this port. |
-
----
-
-## Authentication
-
-Two options:
-
-**Option A — Token (recommended):**
-1. In Megaplan, go to **Settings → Integration → API**.
-2. Generate an access token.
-3. Use it as `MEGAPLAN_TOKEN`.
-
-**Option B — Password grant:**
-1. Use your Megaplan login email + password.
-2. The server fetches an access token via `/api/v3/auth/access_token` on the first request and caches it in memory. On HTTP 401 the cache is cleared and re-auth happens automatically.
-
----
-
-## Demo Prompts
-
-Try these in your MCP client:
-
-> "What active tasks do I have? Sort by urgency."
-
-> "Create a task 'Review Q2 budget' assigned to user 42, deadline next Friday."
-
-> "Show me deals in the 'Sales' pipeline (program 1) with status 'in_progress'."
-
-> "Add a comment to deal 1234: 'Met with the client today, going to send proposal Monday.'"
-
-> "List all employees in the 'Marketing' department."
-
-> "Create a deal for 250,000 RUB in pipeline 1 — name 'Acme Corp annual contract'."
-
-> Use the `my-tasks-today` MCP prompt to get a daily standup view.
-
----
+| `MEGAPLAN_DOMAIN` | Yes | Account host (`yourcompany` → `yourcompany.megaplan.ru`, or a full host) |
+| `MEGAPLAN_TOKEN` | One of | Bearer access token |
+| `MEGAPLAN_LOGIN` | One of | Login email (if no token) |
+| `MEGAPLAN_PASSWORD` | One of | Password (if no token) |
+| `MEGAPLAN_DEBUG` | No | `1` to log full upstream error bodies |
+| `PORT` | No | HTTP port for `--http` mode (default: 3000) |
+| `MCP_HTTP_TOKEN` | `--http` | Bearer token required to call `/mcp` (server refuses to start without it) |
+| `HOST` | No | Bind address for `--http` (default `127.0.0.1`) |
+| `MCP_HTTP_ALLOWED_HOSTS` | No | Comma-separated allowed `Host` values (default loopback:port) |
+| `MCP_HTTP_BODY_LIMIT` | No | Max request body size (default `1mb`) |
+| `MCP_HTTP_MAX_SESSIONS` | No | Max concurrent sessions (default `100`) |
+| `MCP_HTTP_SESSION_TTL_MS` | No | Idle session eviction TTL (default 30 min) |
+
+## Migrating from older versions
+
+Applies to the previously published 8-tool builds (`1.x`–`3.0.0`):
+
+- `get_*` list tools: `offset` → `page_after` (cursor); `filter_status` now takes
+  status **code(s)**, not names like `active`.
+- Output is a compact summary by default — pass `raw: true` for the old raw JSON.
+- `create_comment`: the text field is now `content` (was `text`).
+- `--http`: set `MCP_HTTP_TOKEN`; the default bind is now `127.0.0.1`.
+
+## Verification status
+
+Most behaviour is confirmed against the official v3 RAML and real v3 client
+libraries. A few items are best-effort from docs and marked `TODO(live-verify)`
+in the source (and `experimental` here), pending a test against a live account:
+auth body encoding, the free-text search param name, the `get_current_user`
+endpoint, and the task/deal status-change field shape. Errors are surfaced
+clearly (set `MEGAPLAN_DEBUG=1` for full detail) so any mismatch is diagnosable.
+
+## Referral
+
+Get **20-50% recurring** commission by referring Megaplan:
+
+- [Megaplan Partner Program](https://megaplan.ru/partners/)
+- Sign up as a partner, get your referral link.
+- Every client you bring = recurring revenue share.
 
 ## Development
 
 ```bash
-pnpm install
-pnpm --filter @theyahia/megaplan-mcp build
-pnpm --filter @theyahia/megaplan-mcp test
-pnpm --filter @theyahia/megaplan-mcp dev   # tsx watch mode
-```
-
-Project layout:
-
-```
-servers/megaplan/
-├── src/
-│   ├── index.ts          — bin entry, runServer
-│   ├── server.ts         — createServer factory + 8 tools + 2 prompts
-│   ├── client.ts         — BaseHttpClient + MegaplanAuthStrategy (token OR Password grant)
-│   ├── types.ts          — TypeScript types
-│   └── tools/
-│       ├── comments.ts
-│       ├── deals.ts
-│       ├── employees.ts
-│       ├── projects.ts
-│       └── tasks.ts
-└── tests/
-    ├── client.test.ts    — token + Password grant + 401 re-auth + body
-    └── server.test.ts    — createServer factory smoke
+npm install
+npm run build        # tsc -> dist/
+npm run typecheck    # tsc --noEmit (src + tests)
+npm run lint         # eslint
+npm test             # vitest
+npm run dev          # stdio mode with tsx
+npm run start:http   # HTTP mode (needs MCP_HTTP_TOKEN)
 ```
 
----
-
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT

package/dist/client.d.ts

@@ -1,14 +1,4 @@
-/**
- * Megaplan API client.
- *
- * Custom auth that supports BOTH:
- *   1. Direct token via MEGAPLAN_TOKEN env var (preferred)
- *   2. Password grant via MEGAPLAN_LOGIN + MEGAPLAN_PASSWORD (with token caching)
- *
- * Wraps @theyahia/mcp-core's BaseHttpClient. Re-exports megaplanGet/megaplanPost
- * as functional API so tools/* keep their signatures unchanged.
- */
-export declare function resetClient(): void;
-export declare function megaplanGet(path: string, params?: Record<string, string>): Promise<unknown>;
+/** Test helper: reset cached auth state between cases. */
+export declare function __resetAuth(): void;
+export declare function megaplanGet(path: string, params?: Record<string, unknown>): Promise<unknown>;
 export declare function megaplanPost(path: string, body: unknown): Promise<unknown>;
-//# sourceMappingURL=client.d.ts.map