@taiga-ai/mcp-server 0.0.1-dev.60 → 0.0.1-dev.62

package/src/tools/backlogs.ts

@@ -1,53 +1,10 @@
+// Backlog tools are reserved for post-beta.
+// The beta MCP server focuses on the knowledge base (policies, skills, team docs).
+
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
 
-export function registerBacklogTools(server: McpServer, client: TaigaClient) {
-  if (client.hasCapability('backlog:read')) {
-    server.tool(
-      'taiga_list_backlog_items',
-      'List backlog items (features, tasks, stories) for a project. ' +
-        'Returns item name, status, planning status, and priority.',
-      {
-        projectId: z.string().uuid().describe('Project ID'),
-        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
-      },
-      async (params) => {
-        const result = await client.listBacklogItems(params.projectId, { limit: params.limit });
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
-    );
-
-    server.tool(
-      'taiga_get_backlog_item',
-      'Get detailed information about a specific backlog item, including its active plan and steps.',
-      {
-        itemId: z.string().uuid().describe('Backlog item ID'),
-      },
-      async (params) => {
-        const result = await client.getBacklogItem(params.itemId);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
-    );
-  }
-
-  if (client.hasCapability('projects:read')) {
-    server.tool(
-      'taiga_list_environments',
-      'List deployment environments (dev, staging, production) for a project.',
-      {
-        projectId: z.string().uuid().describe('Project ID'),
-      },
-      async (params) => {
-        const result = await client.listEnvironments(params.projectId);
-        return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
-        };
-      }
-    );
-  }
+export function registerBacklogTools(_server: McpServer, _client: TaigaClient) {
+  // No backlog tools in beta -- will be added when the MCP server
+  // expands beyond the knowledge base use case.
 }

package/src/tools/documents.ts

@@ -1,31 +1,47 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
+import { summarizeList } from './summarize.js';
 
 export function registerDocumentTools(server: McpServer, client: TaigaClient) {
+  // ── Company-level policy documents ──────────────────────────────────
+
   if (client.hasCapability('tenant:documents:read')) {
     server.tool(
       'taiga_list_documents',
-      'List company-level policy documents (security, data privacy, SDLC, etc). ' +
-        'These are the governance documents that guide all projects.',
+      'List company-level policy documents (names and types only). ' +
+        'Policies define security, data privacy, SDLC, operations, architecture, and compliance rules ' +
+        'that apply across all teams and projects. ' +
+        'Use taiga_get_document with the document type to read the full policy content.',
       {
         limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
         const result = await client.listTenantDocuments(params);
+        const summaries = summarizeList(result.data as Record<string, unknown>[]);
         return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
         };
       }
     );
 
     server.tool(
       'taiga_get_document',
-      'Get the full content of a specific policy document by type. ' +
-        'Common types: security_policy, data_privacy_policy, sdlc_policy, architecture_standards.',
+      'Get the full content of a company policy document. ' +
+        'Use this when you need to understand security requirements, data handling rules, ' +
+        'architecture standards, or compliance controls that apply to your code. ' +
+        'Types: policy_security, policy_data, policy_sdlc, policy_ops, policy_tic, ' +
+        'policy_risk, policy_architecture, policy_supply_chain, policy_acceptable_use, policy_ip.',
       {
-        type: z.string().describe('Document type (e.g. security_policy, sdlc_policy)'),
+        type: z
+          .string()
+          .describe(
+            'Document type -- get available types from taiga_list_documents. ' +
+              'Common: policy_security, policy_data, policy_sdlc, policy_architecture'
+          ),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
         const result = await client.getTenantDocument(params.type);
         return {
@@ -38,11 +54,14 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
   if (client.hasCapability('tenant:documents:write')) {
     server.tool(
       'taiga_update_document',
-      'Update the draft content of a policy document. Only updates the draft -- does not publish.',
+      'Update the draft content of a company policy document. ' +
+        'Only updates the draft -- does not publish. Use this when you notice a policy ' +
+        'is outdated or needs corrections while reviewing code.',
       {
-        type: z.string().describe('Document type (e.g. security_policy)'),
-        data: z.record(z.string(), z.unknown()).describe('Document content to save'),
+        type: z.string().describe('Document type (e.g. policy_security, policy_sdlc)'),
+        data: z.record(z.string(), z.unknown()).describe('Document content to save as JSON'),
       },
+      { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
       async (params) => {
         const { type, ...body } = params;
         const result = await client.saveTenantDocumentDraft(type, body as { data: Record<string, unknown> });
@@ -52,4 +71,77 @@ export function registerDocumentTools(server: McpServer, client: TaigaClient) {
       }
     );
   }
+
+  // ── Team documents ──────────────────────────────────────────────────
+
+  if (client.hasCapability('teams:read')) {
+    server.tool(
+      'taiga_list_team_documents',
+      'List documents for a specific team (names and types only). ' +
+        'Team documents define how the team works: domain context (entities, ubiquitous language), ' +
+        'tech preferences (approved stack), architecture constraints, SLO targets, ' +
+        'definition of done, and team charter. ' +
+        'Use taiga_get_team_document to read the full content.',
+      {
+        teamId: z.string().uuid().describe('Team ID -- get from taiga_list_teams'),
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      { readOnlyHint: true, openWorldHint: false },
+      async (params) => {
+        const result = await client.listTeamDocuments(params.teamId, { limit: params.limit });
+        const summaries = summarizeList(result.data as Record<string, unknown>[]);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
+        };
+      }
+    );
+
+    server.tool(
+      'taiga_get_team_document',
+      'Get the full content of a specific team document. ' +
+        'Use this when you need the team domain context (ubiquitous language, entities, business rules), ' +
+        'tech preferences (approved stack, patterns), or architecture constraints. ' +
+        'Types: team_charter, definition_of_done, tech_preferences, ' +
+        'architecture_constraints, slo_targets, domain_context.',
+      {
+        teamId: z.string().uuid().describe('Team ID -- get from taiga_list_teams'),
+        type: z
+          .string()
+          .describe(
+            'Document type -- get available types from taiga_list_team_documents. ' +
+              'Most useful: domain_context (entities, language), tech_preferences (stack, patterns)'
+          ),
+      },
+      { readOnlyHint: true, openWorldHint: false },
+      async (params) => {
+        const result = await client.getTeamDocument(params.teamId, params.type);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+
+  // Team document write requires both teams:read (to find the team) and tenant:documents:write
+  if (client.hasCapability('teams:read') && client.hasCapability('tenant:documents:write')) {
+    server.tool(
+      'taiga_update_team_document',
+      'Update the draft content of a team document. ' +
+        'Only updates the draft -- does not publish. Use this when you notice team conventions, ' +
+        'domain context, or tech preferences need updating while working on the codebase.',
+      {
+        teamId: z.string().uuid().describe('Team ID -- get from taiga_list_teams'),
+        type: z.string().describe('Document type (e.g. domain_context, tech_preferences)'),
+        data: z.record(z.string(), z.unknown()).describe('Document content to save as JSON'),
+      },
+      { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      async (params) => {
+        const { teamId, type, ...body } = params;
+        const result = await client.saveTeamDocumentDraft(teamId, type, body as { data: Record<string, unknown> });
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
 }

package/src/tools/index.ts

@@ -9,6 +9,9 @@ import { registerSkillTools } from './skills.js';
  * Register all MCP tools based on the API key's effective capabilities.
  * Only tools matching the key's scopes are registered -- the AI assistant
  * never sees tools it can't use.
+ *
+ * Beta scope: Knowledge base access (policies, skills, team documents).
+ * Post-beta: Projects, backlog items, environments, composite tools.
  */
 export function registerAllTools(server: McpServer, client: TaigaClient): void {
   registerProjectTools(server, client);

package/src/tools/projects.ts

@@ -1,17 +1,43 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
+import { summarizeList } from './summarize.js';
 
 export function registerProjectTools(server: McpServer, client: TaigaClient) {
+  if (client.hasCapability('teams:read')) {
+    server.tool(
+      'taiga_list_teams',
+      'List all teams in the organization. Use this to find team IDs ' +
+        'for reading team documents, skills, and understanding team structure. ' +
+        'Teams own domain context, tech preferences, and architecture constraints.',
+      {
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      { readOnlyHint: true, openWorldHint: false },
+      async (params) => {
+        const result = await client.listTeams(params);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+
   if (client.hasCapability('projects:read')) {
     server.tool(
       'taiga_list_projects',
-      'List all projects in the organization. Returns project name, status, team, and metadata.',
+      'List projects in the organization. Use this to find the project you are working on ' +
+        'so you can read its specification, architecture, and threat model. ' +
+        'Can filter by team or status.',
       {
-        teamId: z.string().uuid().optional().describe('Filter by team ID'),
-        status: z.enum(['draft', 'active', 'archived']).optional().describe('Filter by status'),
+        teamId: z.string().uuid().optional().describe('Filter by team ID -- get team IDs from taiga_list_teams'),
+        status: z
+          .enum(['draft', 'active', 'archived'])
+          .optional()
+          .describe('Filter by status (draft = intake in progress, active = development)'),
         limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
         const result = await client.listProjects(params);
         return {
@@ -21,29 +47,46 @@ export function registerProjectTools(server: McpServer, client: TaigaClient) {
     );
 
     server.tool(
-      'taiga_get_project',
-      'Get detailed information about a specific project by ID.',
+      'taiga_list_project_documents',
+      'List documents for a specific project (names and types only). ' +
+        'Project documents are generated during intake: specification (requirements), ' +
+        'architecture (system design), technology decisions, data flow, privacy assessment, ' +
+        'threat model (security risks), risk register, and user flow. ' +
+        'Use taiga_get_project_document to read the full content.',
       {
-        id: z.string().uuid().describe('Project ID'),
+        projectId: z.string().uuid().describe('Project ID -- get from taiga_list_projects'),
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
-        const result = await client.getProject(params.id);
+        const result = await client.listProjectDocuments(params.projectId, { limit: params.limit });
+        const summaries = summarizeList(result.data as Record<string, unknown>[]);
         return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
         };
       }
     );
-  }
 
-  if (client.hasCapability('teams:read')) {
     server.tool(
-      'taiga_list_teams',
-      'List all teams in the organization.',
+      'taiga_get_project_document',
+      'Get the full content of a specific project document. ' +
+        'Use this when you need to understand what to build (specification), ' +
+        'how the system is designed (architecture), what security risks exist (threat model), ' +
+        'or what technology choices were made (technology_decisions). ' +
+        'Types: specification, architecture, technology_decisions, data_flow, ' +
+        'privacy_assessment, threat_model, risk_register, user_flow.',
       {
-        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+        projectId: z.string().uuid().describe('Project ID -- get from taiga_list_projects'),
+        type: z
+          .string()
+          .describe(
+            'Document type -- get available types from taiga_list_project_documents. ' +
+              'Common: specification, architecture, threat_model, technology_decisions'
+          ),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
-        const result = await client.listTeams(params);
+        const result = await client.getProjectDocument(params.projectId, params.type);
         return {
           content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
         };

package/src/tools/skills.ts

@@ -1,33 +1,39 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import type { TaigaClient } from '../client.js';
+import { summarizeList } from './summarize.js';
 
 export function registerSkillTools(server: McpServer, client: TaigaClient) {
-  // Skills require tenant:documents:read as they're part of the knowledge base
   if (client.hasCapability('tenant:documents:read')) {
     server.tool(
       'taiga_list_skills',
-      'List agent skills available in the organization. ' +
-        'Skills are reusable knowledge modules that guide AI agents (coding standards, ' +
-        'architecture patterns, deployment procedures, etc).',
+      'List agent skills available in the organization (names and descriptions only). ' +
+        'Skills are reusable knowledge modules that guide coding: coding standards, ' +
+        'security requirements, architecture patterns, database conventions, etc. ' +
+        'Use taiga_get_skill with the skill ID to read the full content.',
       {
         limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
         const result = await client.listSkills(params);
+        const summaries = summarizeList(result.data as Record<string, unknown>[]);
         return {
-          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+          content: [{ type: 'text' as const, text: JSON.stringify(summaries, null, 2) }],
         };
       }
     );
 
     server.tool(
       'taiga_get_skill',
-      'Get the full content of a specific agent skill by ID. ' +
-        'Returns the skill definition including instructions, context, and metadata.',
+      'Get the full content of a specific agent skill. ' +
+        'Use this when you need detailed coding guidelines, patterns, or conventions ' +
+        'for a specific topic (e.g., security requirements, API design, testing strategy). ' +
+        'Returns the complete markdown content with code examples and best practices.',
       {
-        id: z.string().uuid().describe('Skill ID'),
+        id: z.string().uuid().describe('Skill ID -- get from taiga_list_skills'),
       },
+      { readOnlyHint: true, openWorldHint: false },
       async (params) => {
         const result = await client.getSkill(params.id);
         return {
@@ -36,4 +42,27 @@ export function registerSkillTools(server: McpServer, client: TaigaClient) {
       }
     );
   }
+
+  if (client.hasCapability('tenant:documents:write')) {
+    server.tool(
+      'taiga_update_skill',
+      'Update an agent skill (coding standards, patterns, conventions). ' +
+        'Use this when you notice a skill is outdated, incomplete, or needs corrections ' +
+        'while working on the codebase. Changes are saved immediately.',
+      {
+        id: z.string().uuid().describe('Skill ID -- get from taiga_list_skills'),
+        name: z.string().optional().describe('Updated skill name'),
+        description: z.string().optional().describe('Updated skill description'),
+        content: z.string().optional().describe('Updated skill content (markdown)'),
+      },
+      { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+      async (params) => {
+        const { id, ...body } = params;
+        const result = await client.updateSkill(id, body);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
 }

package/src/tools/summarize.ts

@@ -0,0 +1,30 @@
+/**
+ * Strip heavy content from list responses to avoid context window bloat.
+ *
+ * List endpoints return summaries (id, name, description, metadata).
+ * Get endpoints return the full content.
+ *
+ * This keeps list calls cheap (~100 tokens per item) and lets the AI
+ * selectively load full content only for the items it needs.
+ */
+
+/** Fields to strip from list responses -- these contain the bulk content. */
+const HEAVY_FIELDS = ['content', 'data', 'sections'];
+
+/**
+ * Remove heavy content fields from each item in an array.
+ * Preserves all metadata (id, name, description, type, dates, etc).
+ */
+export function summarizeList<T extends Record<string, unknown>>(
+  items: T[]
+): Omit<T, 'content' | 'data' | 'sections'>[] {
+  return items.map((item) => {
+    const summary = { ...item };
+    for (const field of HEAVY_FIELDS) {
+      if (field in summary) {
+        delete summary[field];
+      }
+    }
+    return summary;
+  });
+}