npm - @itm-platform/mcp-server - Versions diffs - 1.0.0 → 1.0.3 - Mend

@itm-platform/mcp-server 1.0.0 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 ITM Platform
+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 CHANGED Viewed

@@ -1,193 +1,239 @@
-# ITM.MCP
+# ITM Platform MCP Server
-> For cross-cutting documentation (debugging, database schema, environments, API versioning, build commands), see the [parent README](../README.md#documentation-index).
+Connect ITM Platform to AI assistants through the [Model Context Protocol](https://modelcontextprotocol.io). The ITM Platform MCP server lets MCP-compatible clients search projects, inspect budgets, summarize portfolio health, create tasks, log risks and issues, and update project details using your ITM Platform permissions.
-MCP (Model Context Protocol) server for ITM Platform. Exposes project management data to AI assistants -- Claude, ChatGPT, VS Code Copilot, Cursor, JetBrains -- through a universal open protocol.
+It works with Claude, VS Code, Cursor, OpenAI Codex, Windsurf, JetBrains AI Assistant, and any other client that supports MCP.
-**Status:** Phase 2 in progress -- 20 tools (15 read + 5 write), 6 resources, 4 prompts. OAuth scope enforcement, audit logging, and token exchange in place. 137 unit tests, 23 E2E tests.
+- Public docs: [developers.itmplatform.com/mcp](https://developers.itmplatform.com/mcp/)
+- npm package: [@itm-platform/mcp-server](https://www.npmjs.com/package/@itm-platform/mcp-server)
+- Hosted MCP URL: `https://api.itmplatform.com/v2/_/mcp/`
-See [House Rules](../House-rules.md) for coding conventions.
+## Quick Start
-## How it works
+### Hosted connection with OAuth
-MCP is a JSON-RPC 2.0 protocol that lets AI assistants discover and call tools on external servers. The server supports two transports:
-- **HTTP + OAuth (recommended)** -- AI clients connect to a hosted URL and authenticate via OAuth 2.1 (PKCE). No local install needed.
-- **stdio** -- AI clients spawn the server as a local child process. Auth via API key.
+Use the hosted server if your AI client supports remote MCP servers. There is nothing to install: add the URL, sign in with your ITM Platform account, and approve the requested access.
+```bash
+claude mcp add --scope user --transport http itm-platform https://api.itmplatform.com/v2/_/mcp/
 ```
-AI Client (Claude, Cursor, VS Code, Codex...)
-  |
-  |  HTTP (remote) or stdio (local)
-  v
-ITM.MCP Server
-  |  authenticates as the user, calls ITM APIs
-  v
-ITM.API Gateway --> DataMart (GraphQL) + v2 REST (users, reference data)
+For other MCP clients, use this remote URL:
+```text
+https://api.itmplatform.com/v2/_/mcp/
 ```
-**Key point:** The AI model never sees user credentials. Auth is handled by the MCP server. The model only sees tool names, descriptions, and results.
+OAuth is the recommended setup for most users because your AI client never sees your ITM Platform password or API key.
-### Three MCP primitives
+After adding the server, open your AI client, type `/mcp` where slash commands are supported, select `itm-platform`, and complete the ITM Platform OAuth login when prompted.
-| Primitive | Who controls it | What it does | Example |
-|-----------|----------------|--------------|---------|
-| **Tools** | AI model decides when to call | Executable read/write operations | `search_projects`, `get_project_budget` |
-| **Resources** | Client app loads as context | Read-only reference data (schemas, docs) | `itm://schema/component` |
-| **Prompts** | User triggers a workflow template | Pre-composed multi-tool request | `/project_status` fetches project + tasks + risks + budget in one shot |
+### Local connection with an API key
-## Quick start
+Use the npm package if you prefer to run the server locally, work behind a firewall, or need to connect to a self-hosted ITM Platform instance.
 ```bash
-npm install
-cp .env.sample .env   # edit with your credentials
-npm test              # unit tests (124 tests)
-npm run build         # compile TypeScript to dist/
-npm run dev           # HTTP dev server on port 6170 (for testing with curl)
-npm run test:e2e      # E2E tests (requires local ITM.API + DataMart)
+npx @itm-platform/mcp-server
 ```
-## End-user setup
+Your MCP client must pass these environment variables to the server:
+| Variable | Value |
+|----------|-------|
+| `ITM_API_URL` | `https://api.itmplatform.com` |
+| `ITM_COMPANY` | Your company/account slug |
+| `ITM_API_KEY` | Your personal API key from ITM Platform |
+Example stdio configuration:
+```json
+{
+  "mcpServers": {
+    "itm-platform": {
+      "command": "npx",
+      "args": ["@itm-platform/mcp-server"],
+      "env": {
+        "ITM_API_URL": "https://api.itmplatform.com",
+        "ITM_COMPANY": "{your-account}",
+        "ITM_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
-For end-user setup instructions (OAuth, per-client configuration, npm package), see the [APIDocs site](APIDocs/).
+To create an API key, log in to ITM Platform, open **My Profile**, and generate a key from the **API Key** section.
-**Quick connect (OAuth):**
+After configuring the local server, restart your AI client and use `/mcp` or the client's MCP server list to confirm `itm-platform` is connected.
-```bash
-claude mcp add --scope user --transport http itm-platform https://api.itmplatform.com/v2/_/mcp/
-```
+## What Can an Agent Do?
-**Quick connect (npm, local):**
+From simple lookups to fully automated cross-system workflows, MCP unlocks progressively more powerful use cases.
-```bash
-claude mcp add --scope user itm-platform -- npx @itm-platform/mcp-server
-```
+**Quick lookup** -- Ask a question, get an answer:
-## Server configuration (development / deployment)
+> "What risks are open across my portfolio?"
-| Variable | Stdio | HTTP+OAuth | Description |
-|----------|-------|------------|-------------|
-| `ITM_API_URL` | Required | Required | ITM.API base URL |
-| `ITM_COMPANY` | Required | -- | Company/tenant slug |
-| `ITM_API_KEY` | Required* | -- | Per-user API key (generate from My Profile) |
-| `ITM_TOKEN` | Required* | -- | Session token (alternative to API key) |
-| `PORT` | -- | Required | HTTP listen port |
-| `ITM_AUTH_URL` | -- | Required | Internal OAuth authorization server URL (used for token exchange) |
-| `ITM_AUTH_PUBLIC_URL` | -- | Required* | Public OAuth URL advertised to AI clients. Falls back to `ITM_AUTH_URL` |
-| `MCP_SERVER_URL` | -- | Required | MCP server public URL (OAuth audience) |
-| `LOG_LEVEL` | Optional | Optional | Pino log level: `debug`, `info`, `warn`, `error` (default: `info`) |
-| `ITM_AUDIT_ENABLED` | Optional | Optional | Enable audit logging to ITM backend |
+**Multi-step analysis** -- The agent chains multiple tools and synthesizes results:
-\* One of `ITM_API_KEY` or `ITM_TOKEN` is required for stdio mode.
+> "Review every project ending this quarter. Flag any with budget overruns, open high-impact risks, or task completion below 60%."
-In HTTP mode, if both `ITM_AUTH_URL` and `MCP_SERVER_URL` are set, OAuth is mandatory and every session must provide a Bearer token. If either is missing, the server runs in dev mode using the startup identity.
+**Automated bulk actions** -- The agent reads, decides, and writes across projects:
-On deployed environments, `ITM_AUTH_URL` points to `localhost` for internal server-to-server token exchange. `ITM_AUTH_PUBLIC_URL` must be set to the public URL so AI clients can discover the OAuth authorization server.
+> "For every project still in Planning status with a start date in the past, update the status to Execution and create a kick-off checklist task assigned to the project manager."
-## Tools (Phase 1 -- read-only)
+**Scheduled intelligence** -- An agent runs on a schedule with no human prompt, pulling overdue tasks every Monday and posting a summary to Slack grouped by project manager.
-### DataMart-backed (fast, single-query reads)
+**Cross-system orchestration** -- Combine ITM Platform's MCP with other MCP servers (GitHub, Slack, Google Calendar, email). When a developer merges a PR, an agent finds the matching ITM Platform task, marks it complete, and if the project hits 100%, drafts a closure summary and emails the program manager.
-| Tool | Description |
-|------|-------------|
-| `search_projects` | Find projects by name, status, type, date range |
-| `search_services` | Find services by name, status, type, date range |
-| `get_project` | Full project details with optional subcomponents (tasks, risks, budget, etc.) |
-| `get_service` | Full service details with optional subcomponents |
-| `list_project_tasks` | Tasks for a project |
-| `get_project_risks` | Risks for a project |
-| `get_project_issues` | Issues for a project |
-| `get_project_budget` | Budget summary (top-down, bottom-up, actual, period-end close) |
-| `get_project_purchases` | Purchase orders for a project |
-| `get_project_revenues` | Revenue items for a project |
-| `aggregate_portfolio` | Portfolio analytics -- group, count, sum, avg across all projects |
-| `query_datamart` | Raw DataMart query for advanced analysis (validated, safe operators only) |
+The MCP server authenticates as you, calls ITM Platform APIs, and returns only the data your ITM Platform account is allowed to access.
-### v2 REST-backed (users, reference data)
+## Capabilities
-| Tool | Description |
-|------|-------------|
-| `search_users` | Find team members |
-| `get_user` | User details |
-| `get_reference_data` | Status lists, types, priorities for any entity |
+The server exposes 20 MCP tools, 6 resources, and 4 prompt templates.
-### Write tools (Phase 2 -- v2 REST-backed)
+### Read Tools
-| Tool | Description |
-|------|-------------|
-| `create_task` | Create a new task in a project |
-| `update_task` | PATCH task fields (status, dates, assignee, progress) |
-| `create_risk` | Log a new risk in a project |
-| `create_issue` | Log a new issue in a project |
-| `update_project` | PATCH project fields (name, status, dates, priority) |
+| Tool | What it does |
+|------|--------------|
+| `search_projects` | Find projects by name, status, type, or date range |
+| `get_project` | Retrieve project details, including optional tasks, risks, issues, budget, purchases, and revenues |
+| `search_services` | Find services by name, status, type, or date range |
+| `get_service` | Retrieve service details |
+| `list_project_tasks` | List tasks for a project |
+| `get_project_budget` | Get budget, actuals, revenue, cost, and margin information |
+| `get_project_purchases` | List purchase orders for a project |
+| `get_project_revenues` | List revenue items for a project |
+| `get_project_risks` | List project risks |
+| `get_project_issues` | List project issues |
+| `aggregate_portfolio` | Group and summarize portfolio data |
+| `query_datamart` | Run validated DataMart queries for advanced analysis |
+| `search_users` | Find users and team members |
+| `get_user` | Retrieve user details |
+| `get_reference_data` | Retrieve statuses, types, priorities, and other reference lists |
-Write tools return confirmed state from v2 REST (source of truth). Subsequent DataMart reads may lag 5-60 seconds due to eventual consistency -- this is noted in every write response.
+### Write Tools
-## Prompts
+| Tool | What it does |
+|------|--------------|
+| `create_task` | Add a task to a project |
+| `update_task` | Update task fields such as status, dates, assignee, and progress |
+| `create_risk` | Log a project risk |
+| `create_issue` | Log a project issue |
+| `update_project` | Update project fields such as name, status, dates, and priority |
-Workflow templates the user can trigger. The MCP server returns a pre-composed message that instructs the AI to call the right tools.
+Write operations confirm the saved state from the ITM Platform REST API. DataMart-backed search results may take up to 60 seconds to reflect recent writes.
-| Prompt | What it does |
-|--------|-------------|
-| `/project_status` | Fetches project + tasks + risks + budget, asks AI to summarize |
-| `/portfolio_overview` | Aggregates projects by status/methodology/budget, asks AI for health overview |
-| `/team_workload` | Fetches users + assignments, asks AI for workload analysis |
-| `/risk_analysis` | Fetches risks + issues + budget, asks AI for risk assessment |
+### Resources and Prompts
-## Architecture
+Resources give AI clients read-only context such as DataMart schemas and project calendars. Prompt templates provide guided workflows for common analysis tasks:
-```
-src/
-  server.ts                # MCP server bootstrap (stdio + HTTP, per-session auth)
-  instrument-server.ts     # Tool-call logging + audit wrapper (wraps registerTool)
-  logger.ts                # Pino logger factory (stderr + rotating file in logs/mcp.log)
-  auth/
-    effective-user-context.ts  # User identity type
-    api-key-auth.ts            # API key auth, calls /resolve/identity
-    license-resolver.ts        # License type -> access level
-    oauth-auth.ts              # Phase 2: OAuth token exchange
-    oauth-metadata.ts          # Phase 2: /.well-known/oauth-protected-resource
-    token-extraction.ts        # Bearer token extraction from headers
-  clients/
-    datamart-client.ts     # DataMart GraphQL through gateway
-    rest-client.ts         # v2 REST through gateway (GET, POST, PATCH)
-    audit-client.ts        # Phase 2: audit logging (fire-and-forget)
-  tools/                   # One file per tool group
-    write-tools.ts         # Phase 2: create/update tools (task, risk, issue, project)
-  resources/               # Schema + calendar resources
-  prompts/                 # Workflow templates
-  validation/
-    query-validator.ts     # Allowlist of safe MongoDB operators
-```
+| Prompt | What it helps with |
+|--------|--------------------|
+| `/project_status` | Summarize health, tasks, risks, issues, and budget for one project |
+| `/portfolio_overview` | Analyze portfolio status, methodology, budget, and delivery patterns |
+| `/team_workload` | Review assignments and workload patterns |
+| `/risk_analysis` | Assess risk exposure, issues, and budget impact |
+## Authentication and Permissions
+The MCP server uses the same identity and permission model as ITM Platform.
+| Connection method | Authentication | Best for |
+|-------------------|----------------|----------|
+| Hosted HTTP | OAuth 2.1 with PKCE | Most users and managed AI clients |
+| Local stdio | ITM Platform API key | Local execution, firewalled networks, self-hosted environments |
+OAuth sessions use scopes:
+| Scope | Allows |
+|-------|--------|
+| `mcp:read` | Read-only tools such as search, get, list, aggregate, and query |
+| `mcp:write` | Read tools plus create and update tools |
+API key sessions use the full permissions of the ITM Platform user who generated the key.
-## Access control
+License access:
-| License type | Access |
-|-------------|--------|
-| CompanyAdmin | Full |
-| FullUser | Full |
-| ProjectManager | Blocked in Phase 1 (requires gateway PM-scope injection -- Phase 2) |
-| TeamMember | Blocked |
+| License | MCP access |
+|---------|------------|
+| Company Admin | Full read and write access |
+| Full User | Full read and write access |
+| Project Manager | Not yet available |
+| Team Member | Blocked |
-**OAuth scope enforcement:** OAuth sessions respect granted scopes. Sessions with `mcp:read` only see 15 read tools; `mcp:write` is required to see and use write tools. API-key/stdio sessions get all tools unconditionally (backward compatible).
+Your AI assistant does not receive your ITM Platform password or API key. Project data is returned to the AI client you choose, so the AI provider's data-handling policy applies to any data it processes.
-## Logging
+## Client Setup
-Uses [Pino](https://getpino.io/) (same as DataMart and MSTeamsBot). Logs go to two destinations:
+Use the public docs for client-specific setup:
-- **stderr** -- pretty-printed, colorized (stdout is reserved for the MCP JSON-RPC protocol)
-- **`logs/mcp.log`** -- rotating file relative to the MCP application root, 10 MB max, keeps 5 old files (skipped in test)
+- [Claude Code, Claude Desktop, VS Code, Cursor, Codex, Windsurf, and JetBrains](https://developers.itmplatform.com/mcp/#ai-clients)
+- [Connect with OAuth](https://developers.itmplatform.com/mcp/#setup-oauth)
+- [Connect with an API key](https://developers.itmplatform.com/mcp/#setup-stdio)
+- [Troubleshooting](https://developers.itmplatform.com/mcp/#troubleshooting)
+For any MCP-compatible client, the two connection values are:
+| Method | Value |
+|--------|-------|
+| Remote URL | `https://api.itmplatform.com/v2/_/mcp/` |
+| Local command | `npx @itm-platform/mcp-server` |
+After adding either connection, open the client's MCP command or server list. In clients that support slash commands, type `/mcp`, select `itm-platform`, and authenticate when prompted.
+## Self-Hosting
+For a local stdio server, configure `ITM_API_URL`, `ITM_COMPANY`, and either `ITM_API_KEY` or `ITM_TOKEN`.
+For an HTTP server with OAuth, configure:
+| Variable | Description |
+|----------|-------------|
+| `ITM_API_URL` | ITM Platform API gateway URL |
+| `PORT` | HTTP listen port |
+| `ITM_AUTH_URL` | OAuth authorization server URL used for token exchange |
+| `ITM_AUTH_PUBLIC_URL` | Public OAuth URL advertised to AI clients |
+| `MCP_SERVER_URL` | Public MCP server URL used as the OAuth audience |
+| `LOG_LEVEL` | Optional Pino log level: `debug`, `info`, `warn`, or `error` |
+| `ITM_AUDIT_ENABLED` | Enables server-side audit logging when set to `true` |
+When deployed behind a reverse proxy, `ITM_AUTH_URL` can point to a server-to-server address while `ITM_AUTH_PUBLIC_URL` must be reachable by AI clients.
+## Development
+Requirements:
+- Node.js 20 or later
+- npm
+Install dependencies, run tests, and build:
+```bash
+npm install
+npm test
+npm run build
+```
+Run the HTTP development server:
+```bash
+cp .env.sample .env
+npm run dev
+```
-Set `LOG_LEVEL` in `.env` to control verbosity (`debug`, `info`, `warn`, `error`; default: `info`). All log entries include `{ service: 'mcp', app: 'ITM.MCP' }` base fields and ISO timestamps.
+The package entry point is `dist/server.js`; the npm executable is `mcp-server`.
-HTTP clients (DataMart, REST) log at `debug` level on success (with duration in ms) and `error` on failure.
+## Troubleshooting
-**Tool-call logging:** Every MCP tool invocation is logged at `info` level with tool name, userId, and aiClientId. Completion is logged at `debug` with duration in ms. Failures are logged at `error`.
+If tools do not appear in your AI client, confirm that the server configuration is in the correct file for that client, restart the client, and check that `npx @itm-platform/mcp-server` runs successfully for local setups.
-**Audit:** When `ITM_AUDIT_ENABLED=true`, every tool call (read and write) sends an audit entry to the ITM backend (`/v2/{company}/mcp/audit`). Audit is fire-and-forget -- failures do not affect tool execution. Each entry includes: timestamp, userId, accountId, toolName, parametersHash (SHA-256), success, error (if any), aiClientId, durationMs.
+If authentication fails, regenerate your API key or reconnect the OAuth server so your client receives a fresh token.
-## Specification
+If a write succeeds but a later search shows old data, wait up to 60 seconds. Writes are confirmed from the REST API immediately, while DataMart search indexes update asynchronously.
-Full design, architecture decisions, phased rollout, and E2E test details:
+## More Help
-- [SPEC_MCP_SERVER.md](zz_Specifications/SPEC_MCP_SERVER.md)
+- MCP docs: [modelcontextprotocol.io](https://modelcontextprotocol.io)
+- ITM Platform help: [helpcenter.itmplatform.com](https://helpcenter.itmplatform.com)
+- ITM Platform developer docs: [developers.itmplatform.com/documentation](https://developers.itmplatform.com/documentation)

package/package.json CHANGED Viewed

@@ -1,7 +1,17 @@
 {
   "name": "@itm-platform/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "MCP server for ITM Platform",
+  "license": "MIT",
+  "mcpName": "io.github.itmplatform/mcp-server",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "project-management",
+    "itm-platform",
+    "ai",
+    "model-context-protocol"
+  ],
   "type": "module",
   "main": "dist/server.js",
   "bin": {
@@ -22,7 +32,7 @@
   ],
   "scripts": {
     "dev": "cross-env PORT=6170 node --env-file=.env --import tsx src/server.ts",
-    "build": "tsc",
+    "build": "node scripts/increase-package-version.mjs && tsc",
     "start": "node dist/server.js",
     "test": "vitest run",
     "test:integration": "vitest run --config vitest.integration.config.ts",