@jorgeluismlima/teamwork-mcp 1.0.1 → 1.0.2

package/README.md

@@ -7,14 +7,19 @@ A Model Context Protocol (MCP) server that connects to the Teamwork API, allowin
 This server exposes the following tools:
 
 ### Projects & Time Tracking
-*   **`list_projects`**: Listings projects, filtering by search term.
+*   **`list_projects`**: Comprehensive project listing with 50+ filters (date, health, status, tags, etc.) and full API response support.
 *   **`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.
+*   **`get_time_entries`**: Retrieves detailed time entries with 60+ filters (billed status, users, tags, etc.).
 *   **`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).
 
+### Project Categories
+*   **`list_of_project_categories`**: Lists all project categories with filtering options.
+*   **`get_specific_project_category`**: Retrieves details of a specific category.
+*   **`list_of_teamwork_project_categories`**: Helper tool to list categories.
+
 ### People & Companies
 *   **`get_project_people`**: Lists all people associated with a project.
 *   **`get_person`**: Retrieves detailed information about a specific person (user).

package/dist/index.js

@@ -57,30 +57,105 @@ const handleApiError = (error) => {
     };
 };
 server.tool("list_projects", {
-    searchTerm: z.string().optional().describe("Filter by project name"),
-    page: z.number().optional().describe("Page number"),
-}, async ({ searchTerm, page }) => {
+    updatedAfter: z.string().optional().describe("updated after"),
+    timeMode: z.enum(["timelogs", "estimated"]).optional().describe("profitability time mode"),
+    searchTerm: z.string().optional().describe("filter by project name"),
+    reportType: z.enum(["project", "health"]).optional().describe("define the type of the report"),
+    reportTimezone: z.string().optional().describe("Optional to configure the report dates displayed in a timezone"),
+    reportFormat: z.enum(["csv", "html", "pdf", "xls"]).optional().describe("define the format of the report"),
+    projectType: z.string().optional().describe("filter by project type"),
+    orderMode: z.enum(["asc", "desc"]).optional().describe("order mode"),
+    orderBy: z.enum(["companyname", "datecreated", "duedate", "lastactivity", "name", "namecaseinsensitive", "ownercompany", "starred", "categoryname"]).optional().describe("order by"),
+    notCompletedBefore: z.string().optional().describe("filter by projects that have not been completed before the given date"),
+    minLastActivityDate: z.string().optional().describe("filter by min last activity date"),
+    maxLastActivityDate: z.string().optional().describe("filter by max last activity date"),
+    userId: z.number().optional().describe("filter by user id"),
+    pageSize: z.number().optional().describe("number of items in a page"),
+    page: z.number().optional().describe("page number"),
+    orderByCustomFieldId: z.number().optional().describe("order by custom field id when orderBy is equal to customfield"),
+    minBudgetCapacityUsedPercent: z.number().optional().describe("filter by minimum budget capacity used"),
+    maxBudgetCapacityUsedPercent: z.number().optional().describe("filter by maximum budget capacity used"),
+    useFormulaFields: z.boolean().optional().describe("use formula fields"),
+    skipCounts: z.boolean().optional().describe("SkipCounts allows you to skip doing counts on a list API endpoint"),
+    searchCompanies: z.boolean().optional().describe("include companies in the search"),
+    searchByLetter: z.boolean().optional().describe("search projects beginning with the search term character only"),
+    onlyStarredProjects: z.boolean().optional().describe("filter by starred projects only"),
+    onlyProjectsWithExplicitMembership: z.boolean().optional().describe("only show projects with explicit membership"),
+    onlyProjectsThatCanLogTime: z.boolean().optional().describe("can log time on projects"),
+    onlyProjectsThatCanAddTasks: z.boolean().optional().describe("can add tasks on projects"),
+    onlyArchivedProjects: z.boolean().optional().describe("return only archived projects"),
+    matchAllProjectTags: z.boolean().optional().describe("match all project tags"),
+    matchAllExcludedTags: z.boolean().optional().describe("match all excluded project tags"),
+    isReportDownload: z.boolean().optional().describe("generate a report document"),
+    includeTentativeProjects: z.boolean().optional().describe("include alongside normal projects, tentative ones"),
+    includeTabSystemStatus: z.boolean().optional().describe("include tab system status in response"),
+    includeSubCategories: z.boolean().optional().describe("include sub categories when filtering by ids"),
+    includeStats: z.boolean().optional().describe("include project status counts"),
+    includeProjectUserInfo: z.boolean().optional().describe("fetch user-specific data such as isStarred"),
+    includeProjectProfitability: z.boolean().optional().describe("include project profitability in response"),
+    includeProjectDates: z.boolean().optional().describe("include minimum and maximum start/end dates for projects"),
+    includeCustomFields: z.boolean().optional().describe("include custom fields"),
+    includeCounts: z.boolean().optional().describe("include project related counts"),
+    includeCompletedStatus: z.boolean().optional().describe("include completed projects when filtering by project statuses current,late"),
+    includeArchivedProjects: z.boolean().optional().describe("include archived projects"),
+    hideObservedProjects: z.boolean().optional().describe("hide projects where the logged-in user is just an observer"),
+    alwaysIncludeFiltering: z.boolean().optional().describe("includes filters when project ids are provided"),
+    usersWithExplicitMembershipIds: z.array(z.number()).optional().describe("only show projects that have an explicit common membership with provided user ids"),
+    teamIds: z.array(z.number()).optional().describe("filter by projects that contain users associated with the team ids"),
+    selectedColumns: z.array(z.string()).optional().describe("select the columns to use in exports"),
+    projectTagIds: z.array(z.number()).optional().describe("filter by project tag ids"),
+    projectStatuses: z.array(z.string()).optional().describe("filter by project status (active, current, late, upcoming, completed, deleted)"),
+    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("filter by project healths (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"),
+    includeCustomFieldIds: z.array(z.number()).optional().describe("include specific custom fields"),
+    include: z.array(z.string()).optional().describe("include related data"),
+    featuresEnabled: z.array(z.string()).optional().describe("filter by projects that have features enabled"),
+    excludeTagIds: z.array(z.number()).optional().describe("exclude by project tag ids"),
+    excludeProjectIds: z.array(z.number()).optional().describe("exclude certain project ids"),
+}, async (args) => {
     try {
-        const params = {};
-        if (searchTerm)
-            params.searchTerm = searchTerm;
-        if (page)
-            params.page = page;
+        const params = { ...args };
+        // Helper to join arrays
+        const joinParam = (arr) => arr ? arr.join(',') : undefined;
+        if (args.usersWithExplicitMembershipIds)
+            params.usersWithExplicitMembershipIds = joinParam(args.usersWithExplicitMembershipIds);
+        if (args.teamIds)
+            params.teamIds = joinParam(args.teamIds);
+        if (args.selectedColumns)
+            params.selectedColumns = joinParam(args.selectedColumns);
+        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);
+        if (args.includeCustomFieldIds)
+            params.includeCustomFieldIds = joinParam(args.includeCustomFieldIds);
+        if (args.include)
+            params.include = joinParam(args.include);
+        if (args.featuresEnabled)
+            params.featuresEnabled = joinParam(args.featuresEnabled);
+        if (args.excludeTagIds)
+            params.excludeTagIds = joinParam(args.excludeTagIds);
+        if (args.excludeProjectIds)
+            params.excludeProjectIds = joinParam(args.excludeProjectIds);
         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),
+                    text: JSON.stringify(response.data, null, 2),
                 },
             ],
         };
@@ -129,18 +204,103 @@ server.tool("create_time_entry", {
 });
 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 }) => {
+    updatedAfter: z.string().optional().describe("filter by updated after date"),
+    startDate: z.string().optional().describe("filter by a starting date"),
+    reportFormat: z.string().optional().describe("define the format of the report"),
+    projectStatus: z.string().optional().describe("filter by project status (active, current, late, upcoming, completed, deleted)"),
+    orderMode: z.enum(["asc", "desc"]).optional().describe("order mode"),
+    orderBy: z.enum(["company", "date", "dateupdated", "project", "task", "tasklist", "user", "description", "billed", "billable", "timespent"]).optional().describe("sort order"),
+    invoicedType: z.enum(["all", "invoiced", "noninvoiced"]).optional().describe("filter by invoiced type"),
+    endDate: z.string().optional().describe("filter by an ending date"),
+    deletedAfter: z.string().optional().describe("filter by deleted after date"),
+    billableType: z.enum(["all", "billable", "non-billable"]).optional().describe("filter by billable type"),
+    updatedBy: z.number().optional().describe("filter by the user who updated the timelog"),
+    ticketId: z.number().optional().describe("filter by ticket id"),
+    tasklistId: z.number().optional().describe("filter by tasklist id"),
+    taskId: z.number().optional().describe("filter by task id (deprecated, use taskIds)"),
+    pageSize: z.number().optional().describe("number of items in a page"),
+    page: z.number().optional().describe("page number"),
+    invoiceId: z.number().optional().describe("filter by invoice id"),
+    budgetId: z.number().optional().describe("filter by budget id"),
+    allocationId: z.number().optional().describe("filter by allocation id"),
+    useFallbackMethod: z.boolean().optional().describe("use fallback method"),
+    unattachedTimelogs: z.boolean().optional().describe("filter by timelogs that are directly logged against projects"),
+    skipCounts: z.boolean().optional().describe("SkipCounts allows you to skip doing counts"),
+    showDeleted: z.boolean().optional().describe("include deleted items"),
+    returnCostInfo: z.boolean().optional().describe("used to return the cost rate and total"),
+    returnBillableInfo: z.boolean().optional().describe("used to return the billable rate and total"),
+    onlyStarredProjects: z.boolean().optional().describe("filter by starred projects only"),
+    matchAllTaskTags: z.boolean().optional().describe("match all task tags"),
+    matchAllTags: z.boolean().optional().describe("match all tags"),
+    matchAllProjectTags: z.boolean().optional().describe("match all project tags"),
+    isReportDownload: z.boolean().optional().describe("generate a report document"),
+    includeTotals: z.boolean().optional().describe("include totals"),
+    includeTentativeProjects: z.boolean().optional().describe("include tentative projects"),
+    includePermissions: z.boolean().optional().describe("include permissions"),
+    includeDescendants: z.boolean().optional().describe("include descendants"),
+    includeArchivedProjects: z.boolean().optional().describe("include archived projects"),
+    deletedOnly: z.boolean().optional().describe("only deleted tasks"),
+    checkLocking: z.boolean().optional().describe("check timesheets' locking"),
+    taskTagIds: z.array(z.number()).optional().describe("filter by task tag ids"),
+    taskStatuses: z.array(z.string()).optional().describe("filter by task statuses"),
+    taskIds: z.array(z.number()).optional().describe("filter by task ids"),
+    tagIds: z.array(z.number()).optional().describe("filter by tag ids"),
+    selectedColumns: z.array(z.string()).optional().describe("customise the report by selecting columns"),
+    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("filter by project healths (0: not set, 1: bad, 2: ok, 3: good)"),
+    projectCompanyIds: z.array(z.number()).optional().describe("filter by project company ids"),
+    projectCategoryIds: z.array(z.number()).optional().describe("filter by project category ids"),
+    include: z.array(z.string()).optional().describe("include related data"),
+    ids: z.array(z.number()).optional().describe("filter by ids"),
+    assignedToUserIds: z.array(z.number()).optional().describe("filter by assigned user ids"),
+    assignedToTeamIds: z.array(z.number()).optional().describe("filter by assigned team ids"),
+    assignedToCompanyIds: z.array(z.number()).optional().describe("filter by assigned company ids"),
+    assignedTeamIds: z.array(z.number()).optional().describe("filter by assigned team ids"),
+}, async (args) => {
     try {
-        const params = {};
-        if (page)
-            params.page = page;
-        if (fromDate)
-            params.fromDate = fromDate;
-        if (toDate)
-            params.toDate = toDate;
+        const { projectId, ...restParams } = args;
+        const params = { ...restParams };
+        // Helper to join arrays
+        const joinParam = (arr) => arr ? arr.join(',') : undefined;
+        if (args.taskTagIds)
+            params.taskTagIds = joinParam(args.taskTagIds);
+        if (args.taskStatuses)
+            params.taskStatuses = joinParam(args.taskStatuses);
+        if (args.taskIds)
+            params.taskIds = joinParam(args.taskIds);
+        if (args.tagIds)
+            params.tagIds = joinParam(args.tagIds);
+        if (args.selectedColumns)
+            params.selectedColumns = joinParam(args.selectedColumns);
+        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);
+        if (args.include)
+            params.include = joinParam(args.include);
+        if (args.ids)
+            params.ids = joinParam(args.ids);
+        if (args.assignedToUserIds)
+            params.assignedToUserIds = joinParam(args.assignedToUserIds);
+        if (args.assignedToTeamIds)
+            params.assignedToTeamIds = joinParam(args.assignedToTeamIds);
+        if (args.assignedToCompanyIds)
+            params.assignedToCompanyIds = joinParam(args.assignedToCompanyIds);
+        if (args.assignedTeamIds)
+            params.assignedTeamIds = joinParam(args.assignedTeamIds);
         const response = await axiosInstance.get(`/projects/${projectId}/time.json`, { params });
         return {
             content: [
@@ -358,6 +518,91 @@ server.tool("get_company", {
         return handleApiError(error);
     }
 });
+server.tool("list_of_project_categories", {
+    searchTerm: z.string().optional().describe("Filter by name"),
+    onlyStarredProjects: z.boolean().optional().describe("Filter by starred projects only"),
+    projectStatuses: z.array(z.string()).optional().describe("Filter by project statuses (Comma separated values)"),
+    ids: z.array(z.number()).optional().describe("Filter by specific ids"),
+    fields: z.array(z.string()).optional().describe("Fields to return: id, name, color, count, parent, parentId"),
+}, async (args) => {
+    try {
+        const params = {};
+        if (args.searchTerm)
+            params.searchTerm = args.searchTerm;
+        if (args.onlyStarredProjects !== undefined)
+            params.onlyStarredProjects = args.onlyStarredProjects;
+        const joinParam = (arr) => arr ? arr.join(',') : undefined;
+        if (args.projectStatuses)
+            params.projectStatuses = joinParam(args.projectStatuses);
+        if (args.ids)
+            params.ids = joinParam(args.ids);
+        if (args.fields)
+            params['fields[projectcategories]'] = joinParam(args.fields);
+        const response = await axiosInstance.get("/projectcategories.json", { params });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("get_specific_project_category", {
+    id: z.number().describe("The ID of the category"),
+    searchTerm: z.string().optional().describe("Filter by name"),
+    onlyStarredProjects: z.boolean().optional().describe("Filter by starred projects only"),
+    projectStatuses: z.array(z.string()).optional().describe("Filter by project statuses"),
+    ids: z.array(z.number()).optional().describe("Filter by specific ids"),
+    fields: z.array(z.string()).optional().describe("Fields to return"),
+}, async (args) => {
+    try {
+        const params = {};
+        if (args.searchTerm)
+            params.searchTerm = args.searchTerm;
+        if (args.onlyStarredProjects !== undefined)
+            params.onlyStarredProjects = args.onlyStarredProjects;
+        const joinParam = (arr) => arr ? arr.join(',') : undefined;
+        if (args.projectStatuses)
+            params.projectStatuses = joinParam(args.projectStatuses);
+        if (args.ids)
+            params.ids = joinParam(args.ids);
+        if (args.fields)
+            params['fields[projectcategories]'] = joinParam(args.fields);
+        const response = await axiosInstance.get(`/projectcategories/${args.id}.json`, { params });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(response.data, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return handleApiError(error);
+    }
+});
+server.tool("list_of_teamwork_project_categories", {}, async () => {
+    try {
+        const response = await axiosInstance.get("/projects/teamwork/categories.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);

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP Server for Teamwork",
   "main": "dist/index.js",
   "bin": {
@@ -18,8 +18,16 @@
     "start": "node dist/index.js",
     "dev": "tsc --watch"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "mcp",
+    "teamwork",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "llm",
+    "api"
+  ],
+  "author": "Jorge Luis M. Lima",
   "license": "ISC",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.1",