@jorgeluismlima/teamwork-mcp 1.0.0

package/README.md

@@ -0,0 +1,79 @@
+# Teamwork MCP Server
+
+A Model Context Protocol (MCP) server that connects to the Teamwork API, allowing AI agents to interact with projects, time entries, people, and companies.
+
+## Functionalities (Tools)
+
+This server exposes the following tools:
+
+### Projects & Time Tracking
+*   **`list_projects`**: Listings projects, filtering by search term.
+*   **`create_time_entry`**: Creates a time entry (timelog) for a specific project.
+*   **`get_time_entries`**: Retrieves time entries for a project, with optional date filtering.
+*   **`total_count_of_active_projects`**: Returns the total count of active projects.
+*   **`total_billable_time_per_project`**: Returns total billable minutes per project (optional date range).
+*   **`get_health_stats`**: Returns project health metrics (Good, Bad, OK, etc.), with various filters.
+*   **`get_project_time_totals`**: Returns total hours/minutes for a project (optionally filtered by user).
+
+### People & Companies
+*   **`get_project_people`**: Lists all people associated with a project.
+*   **`get_person`**: Retrieves detailed information about a specific person (user).
+*   **`list_companies`**: Lists companies (clients).
+*   **`get_company`**: Retrieves details of a specific company.
+
+## Configuration
+
+To use this server, you need to configure the following environment variables:
+
+*   **`TEAMWORK_SITE_NAME`**: Your Teamwork site name/subdomain (e.g., `agencyname`).
+*   **`TEAMWORK_USERNAME`**: Your Teamwork username or email.
+*   **`TEAMWORK_PASSWORD`**: Your Teamwork password or API Key.
+
+## Prerequisites
+
+Before using this MCP server, ensure you have:
+
+*   **Node.js**: Version 18 or higher installed. [Download Node.js](https://nodejs.org/)
+*   **Teamwork Account**: You must have an active Teamwork account.
+*   **API Credentials**: You need your Teamwork Site Name and an API Key (or password) to authenticate.
+
+## Installation & Running
+
+1.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+
+2.  **Build the project:**
+    ```bash
+    npm run build
+    ```
+
+3.  **Run the server:**
+    ```bash
+    node dist/index.js
+    ```
+
+## Client Configuration (Example)
+
+To add this server to an MCP client (like Claude Desktop or an IDE extension), add the following to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "teamwork": {
+      "command": "node",
+      "args": [
+        "c:/path/to/teamwork-mcp/dist/index.js"
+      ],
+      "env": {
+        "TEAMWORK_SITE_NAME": "your-site-name",
+        "TEAMWORK_USERNAME": "your-username",
+        "TEAMWORK_PASSWORD": "your-password-or-api-key"
+      }
+    }
+  }
+}
+```
+
+> **Note:** Replace `c:/path/to/teamwork-mcp/dist/index.js` with the absolute path to the built `index.js` file on your system.

package/dist/index.js

@@ -0,0 +1,369 @@
+#!/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";
+import dotenv from "dotenv";
+const originalWrite = process.stdout.write.bind(process.stdout);
+// @ts-ignore
+process.stdout.write = () => true;
+dotenv.config();
+// @ts-ignore
+process.stdout.write = originalWrite;
+const TEAMWORK_SITE_NAME = process.env.TEAMWORK_SITE_NAME;
+const TEAMWORK_USERNAME = process.env.TEAMWORK_USERNAME;
+const TEAMWORK_PASSWORD = process.env.TEAMWORK_PASSWORD;
+if (!TEAMWORK_SITE_NAME || !TEAMWORK_USERNAME || !TEAMWORK_PASSWORD) {
+    console.error("Missing TEAMWORK_SITE_NAME, TEAMWORK_USERNAME, or TEAMWORK_PASSWORD environment variables");
+    process.exit(1);
+}
+const BASE_URL = `https://${TEAMWORK_SITE_NAME}.teamwork.com/projects/api/v3`;
+const server = new McpServer({
+    name: "teamwork-mcp",
+    version: "1.0.0",
+});
+const axiosInstance = axios.create({
+    baseURL: BASE_URL,
+    auth: {
+        username: TEAMWORK_USERNAME,
+        password: TEAMWORK_PASSWORD,
+    },
+    headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    },
+});
+// Helper to handle API errors
+const handleApiError = (error) => {
+    if (axios.isAxiosError(error)) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Teamwork API Error: ${error.response?.status} - ${JSON.stringify(error.response?.data || error.message)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unexpected Error: ${error instanceof Error ? error.message : String(error)}`,
+            },
+        ],
+        isError: true,
+    };
+};
+server.tool("list_projects", {
+    searchTerm: z.string().optional().describe("Filter by project name"),
+    page: z.number().optional().describe("Page number"),
+}, async ({ searchTerm, page }) => {
+    try {
+        const params = {};
+        if (searchTerm)
+            params.searchTerm = searchTerm;
+        if (page)
+            params.page = page;
+        const response = await axiosInstance.get("/projects.json", { params });
+        const simplifiedProjects = response.data.projects.map((p) => ({
+            id: p.id,
+            name: p.name,
+            description: p.description,
+            status: p.status,
+            company: p.company,
+            createdOn: p.createdOn,
+            lastUpdated: p.lastUpdated
+        }));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ projects: simplifiedProjects, meta: response.data.meta }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("create_time_entry", {
+    projectId: z.number().describe("The ID of the project"),
+    description: z.string().describe("Description of the time entry"),
+    date: z.string().regex(/^\d{4}-?\d{2}-?\d{2}$/).describe("Date in YYYYMMDD or YYYY-MM-DD format"),
+    time: z.string().regex(/^\d{2}:\d{2}(:\d{2})?$/).describe("Time in HH:MM or HH:MM:SS format"),
+    hours: z.number().min(0).describe("Number of hours"),
+    minutes: z.number().min(0).max(59).describe("Number of minutes"),
+    isbillable: z.boolean().describe("Whether the time is billable"),
+    personId: z.number().optional().describe("ID of the person (optional)"),
+}, async ({ projectId, description, date, time, hours, minutes, isbillable, personId }) => {
+    try {
+        const payload = {
+            timelog: {
+                description,
+                date,
+                time,
+                hours: hours,
+                minutes: minutes,
+                isBillable: isbillable,
+            },
+        };
+        if (personId) {
+            payload.timelog.personId = personId;
+        }
+        const response = await axiosInstance.post(`/projects/${projectId}/time.json`, payload);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_time_entries", {
+    projectId: z.number().describe("The ID of the project"),
+    page: z.number().optional().describe("Page number"),
+    fromDate: z.string().optional().describe("Start date (YYYYMMDD)"),
+    toDate: z.string().optional().describe("End date (YYYYMMDD)"),
+}, async ({ projectId, page, fromDate, toDate }) => {
+    try {
+        const params = {};
+        if (page)
+            params.page = page;
+        if (fromDate)
+            params.fromDate = fromDate;
+        if (toDate)
+            params.toDate = toDate;
+        const response = await axiosInstance.get(`/projects/${projectId}/time.json`, { params });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_project_people", {
+    projectId: z.number().describe("The ID of the project"),
+}, async ({ projectId }) => {
+    try {
+        const response = await axiosInstance.get(`/projects/${projectId}/people.json`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_person", {
+    personId: z.number().describe("The ID of the person"),
+}, async ({ personId }) => {
+    try {
+        const response = await axiosInstance.get(`/people/${personId}.json`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_project_time_totals", {
+    projectId: z.number().describe("The ID of the project"),
+    userId: z.number().optional().describe("Filter by user ID"),
+    fromDate: z.string().optional().describe("Start date (YYYYMMDD)"),
+    toDate: z.string().optional().describe("End date (YYYYMMDD)"),
+}, async ({ projectId, userId, fromDate, toDate }) => {
+    try {
+        const params = {};
+        if (userId)
+            params.userId = userId;
+        if (fromDate)
+            params.fromDate = fromDate;
+        if (toDate)
+            params.toDate = toDate;
+        const response = await axiosInstance.get(`/projects/${projectId}/time/total.json`, { params });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("total_count_of_active_projects", {}, async () => {
+    try {
+        const response = await axiosInstance.get("/projects/metrics/active.json");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("total_billable_time_per_project", {
+    startDate: z.string().optional().describe("Start date (YYYYMMDD)"),
+    endDate: z.string().optional().describe("End date (YYYYMMDD)"),
+    orderMode: z.string().optional().describe("Order mode (asc, desc). Default: desc"),
+}, async ({ startDate, endDate, orderMode }) => {
+    try {
+        const params = {};
+        if (startDate)
+            params.startDate = startDate;
+        if (endDate)
+            params.endDate = endDate;
+        if (orderMode)
+            params.orderMode = orderMode;
+        const response = await axiosInstance.get("/projects/metrics/billable.json", {
+            params,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_health_stats", {
+    projectStatus: z.string().optional().describe("Filter by project status (active, current, late, upcoming, completed, deleted)"),
+    onlyStarredProjects: z.boolean().optional().describe("Filter by starred projects only"),
+    matchAllProjectTags: z.boolean().optional().describe("Match all project tags"),
+    projectTagIds: z.array(z.number()).optional().describe("Filter by project tag ids"),
+    projectStatuses: z.array(z.string()).optional().describe("Filter by project statuses"),
+    projectOwnerIds: z.array(z.number()).optional().describe("Filter by project owner ids"),
+    projectIds: z.array(z.number()).optional().describe("Filter by project ids"),
+    projectHealths: z.array(z.number()).optional().describe("Project health (0: not set, 1: bad, 2: ok, 3: good)"),
+    projectCompanyIds: z.array(z.number()).optional().describe("Filter by company ids"),
+    projectCategoryIds: z.array(z.number()).optional().describe("Filter by project category ids"),
+}, async (args) => {
+    try {
+        const params = {};
+        if (args.projectStatus)
+            params.projectStatus = args.projectStatus;
+        if (args.onlyStarredProjects !== undefined)
+            params.onlyStarredProjects = args.onlyStarredProjects;
+        if (args.matchAllProjectTags !== undefined)
+            params.matchAllProjectTags = args.matchAllProjectTags;
+        // Helper to join arrays for API
+        const joinParam = (arr) => arr ? arr.join(',') : undefined;
+        if (args.projectTagIds)
+            params.projectTagIds = joinParam(args.projectTagIds);
+        if (args.projectStatuses)
+            params.projectStatuses = joinParam(args.projectStatuses);
+        if (args.projectOwnerIds)
+            params.projectOwnerIds = joinParam(args.projectOwnerIds);
+        if (args.projectIds)
+            params.projectIds = joinParam(args.projectIds);
+        if (args.projectHealths)
+            params.projectHealths = joinParam(args.projectHealths);
+        if (args.projectCompanyIds)
+            params.projectCompanyIds = joinParam(args.projectCompanyIds);
+        if (args.projectCategoryIds)
+            params.projectCategoryIds = joinParam(args.projectCategoryIds);
+        const response = await axiosInstance.get("/projects/metrics/healths.json", {
+            params,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("list_companies", {
+    page: z.number().optional().describe("Page number"),
+    searchTerm: z.string().optional().describe("Filter by search term"),
+}, async ({ page, searchTerm }) => {
+    try {
+        const params = {};
+        if (page)
+            params.page = page;
+        if (searchTerm)
+            params.searchTerm = searchTerm;
+        const response = await axiosInstance.get("/companies.json", { params });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_company", {
+    companyId: z.number().describe("The ID of the company"),
+}, async ({ companyId }) => {
+    try {
+        const response = await axiosInstance.get(`/companies/${companyId}.json`);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Teamwork MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main loop:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jorgeluismlima/teamwork-mcp",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "MCP Server for Teamwork",
+  "main": "dist/index.js",
+  "bin": {
+    "teamwork-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "axios": "^1.6.0",
+    "dotenv": "^16.4.5",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}