@telos.ready/mcp 1.0.0

package/README.md

@@ -0,0 +1,218 @@
+# Telos MCP Server
+
+A Model Context Protocol (MCP) server that provides access to Telos project management tools. This server allows AI assistants to interact with Telos tickets, documentation, and project tasks.
+
+## Features
+
+This MCP server provides 8 tools for managing Telos projects:
+
+### Core Tools
+
+1. **ask-question** - Ask questions about tickets and get AI-powered answers with context
+2. **get-ticket-details** - Retrieve full ticket information including description and comments
+3. **add-ticket-comment** - Add comments to existing tickets
+4. **get-next-task** - Get the next prioritized task for a specific application
+
+### Development Tools
+
+5. **get-git-branch-for-ticket** - Get the correct git branch name for ticket development
+6. **mark-ticket-as-blocked** - Mark tickets as blocked with a reason
+7. **add-documentation** - Create knowledge tickets with documentation content
+8. **update-action-item** - Update the status of action items in tickets
+
+## Installation
+
+### Using with MCP Clients
+
+Add to your MCP client configuration:
+
+#### Claude Desktop
+
+Update your `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "telos": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-telos"],
+      "env": {
+        "TELOS_PERSONAL_ACCESS_TOKEN": "<YOUR_PAT_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+#### Cursor MCP
+
+Update your `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "telos": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-telos"],
+      "env": {
+        "TELOS_PERSONAL_ACCESS_TOKEN": "<YOUR_PAT_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd telos-mcp
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Run locally
+TELOS_PERSONAL_ACCESS_TOKEN=pat_your_token_here node build/index.js
+```
+
+## Configuration
+
+### Required Environment Variables
+
+- `TELOS_PERSONAL_ACCESS_TOKEN` - Your Telos Personal Access Token (starts with `pat_`)
+
+### Optional Environment Variables
+
+- `TELOS_BASE_URL` - Base URL for Telos instance (defaults to `https://go.telosready.com`)
+
+## Getting Your Personal Access Token
+
+1. Log into your Telos instance
+2. Go to Account → Personal Access Tokens
+3. Create a new token with a descriptive name
+4. Copy the token (it starts with `pat_`)
+5. Use it in your MCP configuration
+
+## Tool Usage Examples
+
+### Add a Comment to a Ticket
+
+```json
+{
+  "name": "add-ticket-comment",
+  "arguments": {
+    "ticketReference": "TEL037",
+    "content": "I've reviewed the requirements and have some questions about the implementation approach.",
+    "internal": false
+  }
+}
+```
+
+### Get Ticket Details
+
+```json
+{
+  "name": "get-ticket-details",
+  "arguments": {
+    "ticketReference": "TEL037"
+  }
+}
+```
+
+### Mark Ticket as Blocked
+
+```json
+{
+  "name": "mark-ticket-as-blocked",
+  "arguments": {
+    "ticketReference": "TEL037",
+    "reason": "Waiting for external API documentation"
+  }
+}
+```
+
+### Get Next Task
+
+```json
+{
+  "name": "get-next-task",
+  "arguments": {
+    "applicationSlug": "myapp"
+  }
+}
+```
+
+### Update Action Item Status
+
+```json
+{
+  "name": "update-action-item",
+  "arguments": {
+    "ticketReference": "TEL037",
+    "actionPoint": "Review database schema",
+    "status": "COMPLETED"
+  }
+}
+```
+
+## Error Handling
+
+The server will return appropriate error messages for:
+
+- Authentication failures (invalid PAT token)
+- Missing required parameters
+- Ticket not found
+- Network connectivity issues
+- Telos API errors
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Publishing
+
+```bash
+npm publish --access public
+```
+
+## Advanced Features
+
+For full access to all Telos MCP features, you can also connect directly to your Telos instance:
+
+```json
+{
+  "mcpServers": {
+    "telos-direct": {
+      "type": "sse",
+      "url": "https://go.telosready.com/mcp?apiKey=pat_your_token_here"
+    }
+  }
+}
+```
+
+This provides access to advanced features like:
+
+- AI-powered question answering
+- Real-time ticket updates
+- Advanced action item management
+
+## Support
+
+If you encounter issues:
+
+1. Check that your PAT token is valid and not expired
+2. Verify you have access to the applications/tickets you're trying to access
+3. Ensure your Telos instance URL is correct
+4. Check the MCP client logs for detailed error messages
+
+## License
+
+ISC

package/build/index.js

@@ -0,0 +1,431 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import axios from "axios";
+// Configuration
+const DEFAULT_TELOS_BASE_URL = "https://go.telosready.com";
+// Create server instance
+const server = new McpServer({
+    name: "telos-mcp",
+    version: "1.0.0",
+});
+// HTTP Client for Telos API
+class TelosClient {
+    client;
+    config;
+    constructor(config) {
+        this.config = config;
+        this.client = axios.create({
+            baseURL: config.baseUrl,
+            timeout: 30000,
+            headers: {
+                "User-Agent": "telos-mcp/1.0.0",
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    async testConnection() {
+        try {
+            if (!this.config.apiKey) {
+                console.error("Connection test failed: No API key provided");
+                return false;
+            }
+            const response = await this.client.get("/account/test-pat", {
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+                timeout: 5000, // 5 second timeout for connection test
+            });
+            return response.status === 200;
+        }
+        catch (error) {
+            // Don't log errors here - let the caller handle them
+            return false;
+        }
+    }
+    async post(endpoint, data) {
+        try {
+            if (!this.config.apiKey) {
+                throw new Error("No API key provided. Please set TELOS_PERSONAL_ACCESS_TOKEN environment variable.");
+            }
+            const response = await this.client.post(endpoint, data, {
+                headers: {
+                    Authorization: `Bearer ${this.config.apiKey}`,
+                },
+            });
+            return response.data;
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const status = error.response?.status;
+                const message = error.response?.data?.error ||
+                    error.response?.data?.message ||
+                    error.message;
+                if (status === 401) {
+                    throw new Error(`Authentication failed. Please check your PAT token.`);
+                }
+                else if (status === 404) {
+                    throw new Error(`Resource not found.`);
+                }
+                else {
+                    throw new Error(`API Error (${status}): ${message}`);
+                }
+            }
+            throw error;
+        }
+    }
+}
+// Initialize Telos client
+const apiKey = process.env.TELOS_PERSONAL_ACCESS_TOKEN || "";
+const baseUrl = process.env.TELOS_BASE_URL || DEFAULT_TELOS_BASE_URL;
+// Don't exit immediately - let the server start and handle the error per request
+if (!apiKey) {
+    console.error("⚠️  WARNING: TELOS_PERSONAL_ACCESS_TOKEN environment variable is not set");
+    console.error("Get your PAT from: Account → Personal Access Tokens in your Telos instance");
+    console.error("Server will start but API calls will fail until token is provided");
+}
+const telosClient = new TelosClient({
+    baseUrl,
+    apiKey,
+});
+// Tool 1: Ask Question
+server.tool("ask-question", "Asks a question about a ticket and gets an answer with supporting context. This tool uses the agent service to provide comprehensive answers with relevant documentation. Provide both a ticket reference and a specific question.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference for the ticket you want to ask a question about, which is an uppercase alphabetical code followed by a number, such as "XXX037".'),
+    question: z
+        .string()
+        .describe("The question you want to ask about the ticket."),
+}, async ({ ticketReference, question }) => {
+    try {
+        const result = await telosClient.post("/mcp/ask-question", {
+            ticketReference,
+            question,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error asking question about ticket ${ticketReference}: ${error}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 2: Add Ticket Comment
+server.tool("add-ticket-comment", "Adds a comment to an existing ticket. This tool allows adding a comment to a specific ticket with proper attribution.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference for the ticket you want to add a comment to, which is an uppercase alphabetical code followed by a number, such as "XXX037".'),
+    content: z
+        .string()
+        .describe("The content of the comment to add to the ticket. This can be any text content including markdown."),
+    internal: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Whether this is an internal comment (not visible to clients)."),
+}, async ({ ticketReference, content, internal }) => {
+    try {
+        const result = await telosClient.post("/mcp/add-ticket-comment", {
+            ticketReference,
+            content,
+            internal,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error adding comment to ticket ${ticketReference}: ${error}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 3: Add Documentation (Create Knowledge Ticket)
+server.tool("add-documentation", "Creates a new knowledge ticket with documentation content. Only use this tool if a comment cannot be added directly to a ticket. This tool creates a knowledge ticket that can be used to store and organize documentation, procedures, guides, or any other knowledge-based content for future reference.", {
+    content: z
+        .string()
+        .describe("The documentation content to add. This should be well-formatted markdown content that provides useful information or knowledge."),
+    title: z.string().optional().describe("Title for the knowledge ticket."),
+    applicationSlug: z
+        .string()
+        .describe("The slug of the application that the documentation relates to."),
+}, async ({ content, title, applicationSlug }) => {
+    try {
+        const result = await telosClient.post("/mcp/add-documentation", {
+            content,
+            title,
+            applicationSlug,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error creating documentation: ${error.message}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 4: Get Ticket Details
+server.tool("get-ticket-details", "Gets the details of a ticket. The ticket reference must be provided. This tool will provide the initial description of the ticket and any comments that users have made on the ticket.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference for the requested ticket, which is an uppercase alphabetical code followed by a number, such as "XXX037".'),
+}, async ({ ticketReference }) => {
+    try {
+        const result = await telosClient.post("/mcp/get-ticket-details", {
+            ticketReference,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error getting ticket details for ${ticketReference}: ${error}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 5: Get Next Task
+server.tool("get-next-task", "Gets the next task for a member and provides a ticket reference, next step and instructions for completing the task.", {
+    applicationSlug: z
+        .string()
+        .describe("Application slug must be provided to specify the application for the next task."),
+}, async ({ applicationSlug }) => {
+    try {
+        const result = await telosClient.post("/mcp/get-next-task", {
+            applicationSlug,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error getting next task for application ${applicationSlug}: ${error.message}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 6: Get Git Branch for Ticket
+server.tool("get-git-branch-for-ticket", "Gets the git branch to be used for development work on this ticket. All commits for this ticket must use this branch. Git branches must stay ahead of main.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference, which is an uppercase alphabetical code followed by a number, such as "TEL037".'),
+}, async ({ ticketReference }) => {
+    try {
+        const result = await telosClient.post("/mcp/get-git-branch-for-ticket", {
+            ticketReference,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error getting git branch for ticket ${ticketReference}: ${error}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 7: Mark Ticket as Blocked
+server.tool("mark-ticket-as-blocked", "Marks a ticket as blocked with a specified reason. This tool will load the ticket, add a comment with the blocking reason, and set the ticket status to blocked.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference for the ticket to mark as blocked, which is an uppercase alphabetical code followed by a number, such as "TEL037".'),
+    reason: z
+        .string()
+        .describe("The reason why the ticket is being blocked. This will be added as a comment to the ticket."),
+}, async ({ ticketReference, reason }) => {
+    try {
+        const result = await telosClient.post("/mcp/mark-ticket-as-blocked", {
+            ticketReference,
+            reason,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error blocking ticket ${ticketReference}: ${error.message}`,
+                },
+            ],
+        };
+    }
+});
+// Tool 8: Update Action Item
+server.tool("update-action-item", "Updates the status of an action item in a ticket. This tool finds a specific action item in the ticket or its comments and updates its status to INCOMPLETE, INPROGRESS, or COMPLETED.", {
+    ticketReference: z
+        .string()
+        .describe('The ticket reference for the ticket containing the action item, which is an uppercase alphabetical code followed by a number, such as "TEL037".'),
+    actionPoint: z
+        .string()
+        .describe("The text of the action item to update. This will be matched against existing action items in the ticket."),
+    status: z
+        .enum(["INCOMPLETE", "INPROGRESS", "COMPLETED"])
+        .describe("The new status for the action item. Must be one of: INCOMPLETE, INPROGRESS, COMPLETED"),
+}, async ({ ticketReference, actionPoint, status }) => {
+    try {
+        const result = await telosClient.post("/mcp/update-action-item", {
+            ticketReference,
+            actionPoint,
+            status,
+        });
+        if (result.success) {
+            return {
+                content: [{ type: "text", text: result.result }],
+            };
+        }
+        else {
+            return {
+                content: [{ type: "text", text: `Error: ${result.error}` }],
+            };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error updating action item for ticket ${ticketReference}: ${error.message}`,
+                },
+            ],
+        };
+    }
+});
+async function main() {
+    try {
+        // Initialize transport first
+        const transport = new StdioServerTransport();
+        // Log startup information to stderr (like weather example)
+        console.error("Telos MCP Server starting...");
+        console.error(`Connecting to Telos at: ${baseUrl}`);
+        console.error(`API Key: ${apiKey.substring(0, 8)}...`);
+        // Connect to the transport (this should not fail)
+        await server.connect(transport);
+        // Log success message
+        console.error("✅ Telos MCP Server running on stdio");
+        console.error("Available tools: ask-question, add-ticket-comment, add-documentation, get-ticket-details, get-next-task, get-git-branch-for-ticket, mark-ticket-as-blocked, update-action-item");
+        // Test connection in background without blocking or exiting
+        // This is non-critical and should not cause the server to exit
+        setImmediate(async () => {
+            try {
+                const connected = await Promise.race([
+                    telosClient.testConnection(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Connection test timeout")), 5000)),
+                ]);
+                if (connected) {
+                    console.error("✅ Telos API connection successful");
+                }
+                else {
+                    console.error("⚠️  Telos API connection failed - tools may not work properly");
+                }
+            }
+            catch (error) {
+                console.error("⚠️  Telos API connection test error:", error.message);
+                console.error("Server will continue running - connection will be tested per request");
+            }
+        });
+    }
+    catch (error) {
+        console.error("Fatal error during server initialization:", error);
+        process.exit(1);
+    }
+}
+// Handle process termination gracefully
+process.on("SIGTERM", () => {
+    console.error("Received SIGTERM, shutting down gracefully");
+    process.exit(0);
+});
+process.on("SIGINT", () => {
+    console.error("Received SIGINT, shutting down gracefully");
+    process.exit(0);
+});
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@telos.ready/mcp",
+  "version": "1.0.0",
+  "description": "Telos MCP server for managing tickets and project tasks",
+  "main": "build/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "npm run build"
+  },
+  "bin": {
+    "server-telos": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "telos",
+    "tickets",
+    "project-management",
+    "model-context-protocol"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.13.3",
+    "axios": "^1.7.7",
+    "zod": "^3.25.69"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.10",
+    "typescript": "^5.8.3"
+  }
+}