@telora/mcp-products 0.21.1

package/README.md

@@ -0,0 +1,276 @@
+# @telora/mcp-products
+
+MCP server that exposes Telora product operations to Claude Code. Tools use a consolidated action-based API — each tool handles multiple actions via an `action` parameter (e.g., `telora_product` with `action: "list"` or `action: "create"`).
+
+## Setup
+
+### 1. Add to your project
+
+Create `.mcp.json` in your project root, pointing to the local build:
+
+```json
+{
+  "mcpServers": {
+    "telora-products": {
+      "command": "node",
+      "args": ["mcp/telora-products/dist/index.js"],
+      "env": {
+        "TELORA_TRACKER_ID": "your-tracker-uuid",
+        "TELORA_URL": "http://your-supabase-url:54321",
+        "TELORA_MCP_PROFILE": "human"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Earlier versions used `npx @telora/mcp-products`, but `npx` resolves to a globally installed version which may be outdated. The local build path prevents version drift.
+
+### 2. Register credentials (once per machine)
+
+Ask your Telora org admin to create an AI tracker for you, then register with the code:
+
+```bash
+telora-ai register <registration-code>
+```
+
+Alternatively, set environment variables `TELORA_TRACKER_ID` and `TELORA_URL` in `.mcp.json`.
+
+### 3. Build the MCP server
+
+```bash
+cd mcp/telora-products && npm run build
+```
+
+### 4. Restart Claude Code
+
+The tools will be available immediately.
+
+## Profiles
+
+The `TELORA_MCP_PROFILE` environment variable controls which tools are registered:
+
+| Profile | Use case | Behavior |
+|---------|----------|----------|
+| `human` | Interactive Claude Code sessions | Core tools at startup + `telora_discover` for on-demand loading |
+| `full` | Default, all tools | Everything registered at startup |
+| `execution` | Daemon strategy execution | Delivery/issue/agent tools, no OKR/ideas/workflows |
+| `factory` | Daemon factory execution | Factory + product tools only |
+
+## Tool Discovery (Human Profile)
+
+The human profile uses a two-tier loading strategy to stay within Claude Code's deferred tool budget:
+
+**Startup tools (always available, 21 decomposed):**
+- `telora_product` — 5 actions: list, create, get, update, overview
+- `telora_product_strategy` — 4 actions: list, create, update, reorder
+- `telora_product_delivery` — 6 actions: list, create, update, operationalize, delete, reorder
+- `telora_product_issue` — 4 actions: list, create, update, delete
+- `telora_discover` — 2 actions: list, load
+
+**Deferred domains (loaded on demand via `telora_discover`):**
+
+| Domain | Tools | Actions | Why deferred |
+|--------|-------|---------|--------------|
+| agent | `telora_agent` | 5 | Escalations are infrequent in interactive sessions |
+| context | `telora_product_context`, `telora_product_context_link` | 7 | Context doc management is occasional setup work |
+| connector | `telora_connector_start` | 1 | Daemon launch is a one-time operation |
+| factory | `telora_factory_blueprint_list`, `telora_factory_spec`, `telora_factory_instance` | 8 | Factory workflows are a separate domain |
+| okr | `telora_objective`, `telora_key_result`, `telora_strategy_key_result` | 10 | Goal-setting is periodic, not daily |
+| ideas | `telora_idea`, `telora_idea_connection`, `telora_idea_cluster` | 12 | Brainstorming is a distinct activity |
+| workflows | `telora_workflow` | 5 | Workflow config is admin setup |
+| playbooks | `telora_playbook` | 4 | Template usage is infrequent |
+| profiles | `telora_deployment_profile` | 5 | CI/CD config is setup work |
+
+**Total after full discover: 78 decomposed tools (within the 80 budget).**
+
+### Using telora_discover
+
+```text
+# List all domains with their tool indexes (shows what's available before loading)
+telora_discover(action: "list")
+
+# Load a specific domain
+telora_discover(action: "load", domain: "factory")
+
+# Load everything at once
+telora_discover(action: "load", domain: "all")
+```
+
+The `list` action returns a `toolIndex` per domain — tool names, summaries, available actions, and keywords — so you can decide which domain to load without guessing.
+
+## Available Tools
+
+### Product Management
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_product` | list, create, get, update, overview | Product registry: manage software products and their settings |
+
+### Strategy Management
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_product_strategy` | list, create, update, reorder | Execution roadmap: group deliveries into themed work scopes |
+
+### Delivery Management
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_product_delivery` | list, create, update, operationalize, delete, reorder | Work packages: shippable increments with acceptance criteria |
+
+### Issue Tracking
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_product_issue` | list, create, update, delete | Task tracking: issues, bugs, and context groups within deliveries |
+
+### Agent & Escalation
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_agent` | role_list, escalate, escalation_list, escalation_get, escalation_update | AI agent roles and human-AI escalation requests |
+
+### Context Documents
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_product_context` | list, create, update, delete, reorder | Knowledge base: product context documents for AI agents |
+| `telora_product_context_link` | link, unlink | Attach/detach context documents to strategies or deliveries |
+
+### Factory
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_factory_blueprint_list` | _(no action param)_ | List factory blueprints with gate configs and resource limits |
+| `telora_factory_spec` | create, get, list, update, validate | Define what to build via conversational spec authoring |
+| `telora_factory_instance` | get, update | View and control running factory instances (pause, cancel) |
+
+### OKR Management
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_objective` | create, get, list, update | Strategic objectives with cascading alignment |
+| `telora_key_result` | create, list, update, delete | Measurable targets with metric types and confidence levels |
+| `telora_strategy_key_result` | link, unlink | Connect strategies to key results for traceability |
+
+### Idea Cloud
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_idea` | create, list, update, delete | Capture ideas: observations, hypotheses, references |
+| `telora_idea_connection` | create, list, update, delete | Map relationships between ideas (supports, causes, contradicts) |
+| `telora_idea_cluster` | create, list, update, delete | Group related ideas into clusters |
+
+### Workflows
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_workflow` | list, get, create, update, assign | Configure lifecycle stages, transition guards, and assignments |
+
+### Playbooks
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_playbook` | list, get, create, instantiate | Template strategies with pre-configured deliveries and issues |
+
+### Deployment Profiles
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_deployment_profile` | create, list, get, update, link_to_product | Define target environments and deployment guidelines |
+
+### Connector
+| Tool | Actions | Description |
+|------|---------|-------------|
+| `telora_connector_start` | _(no action param)_ | Launch Telora daemon for autonomous agent execution |
+
+## Usage
+
+Just ask Claude Code naturally:
+
+- "Show me my products in Telora"
+- "Create a new strategy called 'Q1 Launch' for my product"
+- "List all issues for the current delivery"
+- "Create a P0 bug under delivery X"
+
+## Common Workflows
+
+### Create a product with strategy and delivery
+
+```text
+1. telora_product(action: "create", name: "My App")
+2. telora_product_strategy(action: "create", productId: "<id>", name: "MVP Launch")
+3. telora_product_delivery(action: "create", productId: "<id>", name: "Core Features", strategyId: "<id>")
+4. telora_product_issue(action: "create", deliveryId: "<id>", title: "Build login page", issueType: "Task")
+```
+
+### Track work on issues
+
+```text
+1. telora_product_issue(action: "list", deliveryId: "<id>")
+2. telora_product_issue(action: "update", issueId: "<id>", status: "In Progress")
+3. telora_product_issue(action: "update", issueId: "<id>", status: "Done")
+```
+
+### Set up OKRs linked to strategy
+
+```text
+1. telora_objective(action: "create", title: "Increase user retention")
+2. telora_key_result(action: "create", objectiveId: "<id>", title: "Reduce churn to 5%", targetValue: 5, unit: "%")
+3. telora_strategy_key_result(action: "link", strategyId: "<id>", keyResultId: "<id>")
+```
+
+### Load a playbook
+
+```text
+1. telora_playbook(action: "list")
+2. telora_playbook(action: "get", playbookId: "<id>")
+3. telora_playbook(action: "instantiate", playbookId: "<id>", productId: "<id>")
+```
+
+### Manage context documents
+
+```text
+1. telora_product_context(action: "create", productId: "<id>", title: "Architecture Guide", content: "...", includeMode: "always")
+2. telora_product_context_link(action: "link", documentId: "<id>", entityType: "strategy", entityId: "<id>")
+3. telora_product_context(action: "list", productId: "<id>", strategyId: "<id>")
+```
+
+### Assign a workflow to a delivery
+
+```text
+1. telora_workflow(action: "list", entityType: "delivery")
+2. telora_workflow(action: "assign", workflowId: "<id>", entityType: "delivery", entityId: "<id>")
+3. telora_workflow(action: "get", workflowId: "<id>")
+```
+
+### Build an idea cloud
+
+```text
+1. telora_idea(action: "create", productId: "<id>", content: "Users want faster onboarding", sourceType: "observation")
+2. telora_idea(action: "create", productId: "<id>", content: "Reduce sign-up steps to 2", sourceType: "hypothesis")
+3. telora_idea_connection(action: "create", sourceIdeaId: "<id1>", targetIdeaId: "<id2>", connectionType: "supports")
+4. telora_idea_cluster(action: "create", productId: "<id>", name: "Onboarding", centerIdeaIds: ["<id1>", "<id2>"])
+```
+
+## Error Handling
+
+All tools return errors in a consistent format. Common errors:
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| "Invalid access token" | Tracker ID expired or invalid | Regenerate tracker ID in Telora UI |
+| "Rate limit exceeded" | Too many requests | Wait and retry |
+| "Not found" | Resource doesn't exist | Check the ID |
+| "Insufficient permissions" | User lacks access to the org unit | Request access from admin |
+
+## Credential Sources
+
+Credentials are loaded in this order (first found wins):
+
+1. **Environment variables**: `TELORA_TRACKER_ID` and `TELORA_URL`
+2. **telora-ai database**: `~/.syntelyos/ai_tracking.db` (created by `telora-ai register`)
+
+Legacy `TELORA_ACCESS_TOKEN` is still supported but deprecated. Use `TELORA_TRACKER_ID` (UUID) instead.
+
+### Authentication Details
+
+The MCP server authenticates to the Telora `product-api` edge function using a Profile Tracker ID. This is a UUID associated with your user profile.
+
+**To get your Tracker ID:**
+1. Go to Telora > Settings > AI Work Trackers
+2. Click "Generate Tracker ID" on your profile
+3. Copy the UUID
+
+**Tracker expiry:** Tracker IDs expire after 90 days of inactivity. Each successful API call auto-refreshes the expiry.
+
+See [Authentication Guide](../../docs/AUTHENTICATION.md) for full details.

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runInit(argv: string[]): Promise<void>;

package/dist/cli/init.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// ---------------------------------------------------------------------------
+// `npx @telora/mcp-products init` -- interactive setup for Telora MCP server
+// ---------------------------------------------------------------------------
+import { createInterface } from "node:readline/promises";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { callProductApi } from "../shared.js";
+// ---------------------------------------------------------------------------
+// Prompt helpers
+// ---------------------------------------------------------------------------
+async function prompt(rl, question, defaultValue) {
+    const suffix = defaultValue ? ` (${defaultValue})` : "";
+    const answer = await rl.question(`${question}${suffix}: `);
+    return answer.trim() || defaultValue || "";
+}
+async function validateToken(creds) {
+    const result = await callProductApi(creds, { action: "whoami" });
+    return result;
+}
+function writeMcpConfig(configPath, trackerId, teloraUrl) {
+    let existing = {};
+    if (existsSync(configPath)) {
+        try {
+            existing = JSON.parse(readFileSync(configPath, "utf-8"));
+        }
+        catch {
+            // Malformed JSON -- overwrite with fresh config
+            existing = {};
+        }
+    }
+    if (!existing.mcpServers || typeof existing.mcpServers !== "object") {
+        existing.mcpServers = {};
+    }
+    existing.mcpServers["telora-products"] = {
+        command: "npx",
+        args: ["-y", "@telora/mcp-products"],
+        env: {
+            TELORA_TRACKER_ID: trackerId,
+            TELORA_URL: teloraUrl,
+        },
+    };
+    // Ensure parent directory exists (for ~/.claude/.mcp.json)
+    const dir = join(configPath, "..");
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+}
+// ---------------------------------------------------------------------------
+// Main init flow
+// ---------------------------------------------------------------------------
+export async function runInit(argv) {
+    const isGlobal = argv.includes("--global");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        console.log("\nTelora MCP Server Setup\n");
+        const trackerId = await prompt(rl, "Tracker ID");
+        if (!trackerId) {
+            console.error("Tracker ID is required.");
+            process.exit(1);
+        }
+        const teloraUrl = await prompt(rl, "API URL", "https://api.syntelyos.com");
+        // Validate token
+        console.log("\nValidating tracker ID...");
+        const creds = { accessToken: trackerId, teloraUrl };
+        let whoami;
+        try {
+            whoami = await validateToken(creds);
+        }
+        catch {
+            console.error("\nInvalid tracker ID -- check your token and try again.");
+            process.exit(1);
+        }
+        // Write config
+        const configPath = isGlobal
+            ? join(homedir(), ".claude", ".mcp.json")
+            : join(process.cwd(), ".mcp.json");
+        writeMcpConfig(configPath, trackerId, teloraUrl);
+        // Success message
+        const orgName = whoami.trackerName || whoami.organizationId;
+        console.log(`\nConfiguration written to ${configPath}`);
+        console.log(`Organization: ${orgName}`);
+        if (isGlobal) {
+            console.log("(Global config -- applies to all projects)");
+        }
+        console.log("\nRestart Claude Code to activate the MCP server.");
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"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"}

package/dist/handlers/agentHandlers.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type GetCreds } from "../shared.js";
+export declare function registerAgentTools(server: McpServer, getCreds: GetCreds): void;

package/dist/handlers/agentHandlers.js

@@ -0,0 +1,97 @@
+// ---------------------------------------------------------------------------
+// Agent orchestration tool handler (consolidated):
+//   telora_agent (role_list | escalate | escalation_list | escalation_get | escalation_update)
+// ---------------------------------------------------------------------------
+import { z } from "zod";
+import { callProductApi, successResult, validationError, buildFields, wrapHandler, } from "../shared.js";
+export function registerAgentTools(server, getCreds) {
+    server.tool("telora_agent", "AI agent orchestration: manage agent roles and human-AI escalation requests. " +
+        "Agent roles define capabilities assigned to strategies. Escalations are requests from AI agents to humans when blocked. " +
+        "Actions: role_list (list available AI agent roles), escalate (create escalation to human), " +
+        "escalation_list (view pending escalations), escalation_get (details), escalation_update (resolve or dismiss).", {
+        action: z.enum(["role_list", "escalate", "escalation_list", "escalation_get", "escalation_update"]).describe("Action to perform"),
+        escalationId: z.string().uuid().optional().describe("Escalation UUID (required for escalation_get, escalation_update)"),
+        issueId: z.string().uuid().optional().describe("Issue UUID being worked on (escalate only)"),
+        reasonType: z.enum([
+            "decision_needed", "error_encountered", "out_of_scope",
+            "blocked_by_external", "needs_clarification", "security_concern",
+        ]).optional().describe("Type of escalation (required for escalate)"),
+        description: z.string().max(5000).optional().describe("What happened and why escalation is needed (required for escalate)"),
+        whatWasTried: z.string().max(5000).optional().describe("What approaches were attempted (escalate only)"),
+        helpNeeded: z.string().max(5000).optional().describe("Specific help or decision needed from human (escalate only)"),
+        status: z.enum(["pending", "in_review", "resolved", "dismissed"]).optional().describe("Escalation status (escalation_list: filter; escalation_update: new status)"),
+        resolutionNotes: z.string().max(5000).optional().describe("Resolution notes (escalation_update only)"),
+        limit: z.number().int().min(1).max(500).optional().describe("Max results (1-500, default 50)"),
+        offset: z.number().int().min(0).optional().describe("Number of results to skip (default 0)"),
+        detail: z.enum(["titles", "summary", "full"]).optional().describe("Response detail level"),
+    }, wrapHandler(async (params) => {
+        switch (params.action) {
+            case "role_list": {
+                const body = { action: "agent_role_list" };
+                if (params.limit !== undefined)
+                    body.limit = params.limit;
+                if (params.offset !== undefined)
+                    body.offset = params.offset;
+                if (params.detail !== undefined)
+                    body.detail = params.detail;
+                const result = await callProductApi(getCreds(), body);
+                return successResult({ items: result.roles, totalCount: result.totalCount });
+            }
+            case "escalate": {
+                if (!params.reasonType)
+                    return validationError("reasonType required for escalate");
+                if (!params.description)
+                    return validationError("description required for escalate");
+                const fields = buildFields(params, ['reasonType', 'description', 'issueId', 'whatWasTried', 'helpNeeded']);
+                const result = await callProductApi(getCreds(), {
+                    action: "escalation_create",
+                    fields,
+                });
+                return successResult(`Escalation created. A human will review your request.\n\n${JSON.stringify(result.escalation, null, 2)}`);
+            }
+            case "escalation_list": {
+                const fields = {};
+                if (params.status !== undefined)
+                    fields.status = params.status;
+                const body = {
+                    action: "escalation_list",
+                    fields: Object.keys(fields).length > 0 ? fields : undefined,
+                };
+                if (params.limit !== undefined)
+                    body.limit = params.limit;
+                if (params.offset !== undefined)
+                    body.offset = params.offset;
+                if (params.detail !== undefined)
+                    body.detail = params.detail;
+                const result = await callProductApi(getCreds(), body);
+                return successResult({ items: result.escalations, totalCount: result.totalCount });
+            }
+            case "escalation_get": {
+                if (!params.escalationId)
+                    return validationError("escalationId required for escalation_get");
+                const result = await callProductApi(getCreds(), {
+                    action: "escalation_get",
+                    escalationId: params.escalationId,
+                });
+                return successResult(result.escalation);
+            }
+            case "escalation_update": {
+                if (!params.escalationId)
+                    return validationError("escalationId required for escalation_update");
+                const fields = buildFields({ status: params.status, resolutionNotes: params.resolutionNotes });
+                if (Object.keys(fields).length === 0) {
+                    return validationError("At least one field (status, resolutionNotes) must be provided");
+                }
+                const result = await callProductApi(getCreds(), {
+                    action: "escalation_update",
+                    escalationId: params.escalationId,
+                    fields,
+                });
+                return successResult(result.escalation);
+            }
+            default:
+                return validationError(`Unknown action: ${params.action}`);
+        }
+    }));
+}
+//# sourceMappingURL=agentHandlers.js.map

package/dist/handlers/agentHandlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentHandlers.js","sourceRoot":"","sources":["../../src/handlers/agentHandlers.ts"],"names":[],"mappings":"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"}

package/dist/handlers/connectorHandlers.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type GetCreds, type ToolProfile } from "../shared.js";
+export declare function registerConnectorTools(server: McpServer, getCreds: GetCreds, profile?: ToolProfile): void;