@taiga-ai/mcp-server 0.0.1-dev.51

package/src/server.integration.test.ts

@@ -0,0 +1,429 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { TaigaClient } from './client.js';
+import { registerAllTools } from './tools/index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers -- thin wrappers, not abstraction layers
+// ---------------------------------------------------------------------------
+
+/** All capabilities the MCP server understands. */
+const ALL_CAPABILITIES = [
+  'projects:read',
+  'teams:read',
+  'tenant:documents:read',
+  'tenant:documents:write',
+  'backlog:read',
+];
+
+/** All tool names the server can register (sorted for deterministic comparison). */
+const ALL_TOOL_NAMES = [
+  'taiga_get_backlog_item',
+  'taiga_get_document',
+  'taiga_get_project',
+  'taiga_get_skill',
+  'taiga_list_backlog_items',
+  'taiga_list_documents',
+  'taiga_list_environments',
+  'taiga_list_projects',
+  'taiga_list_skills',
+  'taiga_list_teams',
+  'taiga_update_document',
+];
+
+function makeFetchRouter(routes: Record<string, unknown>) {
+  return vi.fn().mockImplementation(async (url: string, init: RequestInit) => {
+    const path = new URL(url).pathname;
+    const method = init?.method ?? 'GET';
+    const key = `${method} ${path}`;
+
+    const body = routes[key] ?? routes[path];
+    if (body !== undefined) {
+      return {
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(JSON.stringify(body)),
+      };
+    }
+    return {
+      ok: false,
+      status: 404,
+      json: () => Promise.resolve({ error: 'Not found' }),
+      text: () => Promise.resolve('Not found'),
+    };
+  });
+}
+
+function introspectionResponse(capabilities: string[]) {
+  return {
+    data: {
+      userId: 'user-1',
+      tenantId: 'tenant-1',
+      email: 'dev@test.com',
+      role: 'member',
+      capabilities,
+    },
+  };
+}
+
+/**
+ * Boots a full MCP Client <-> Server pair connected in-memory.
+ * The TaigaClient uses a route-based fetch mock, so no real HTTP is needed.
+ * Returns both the MCP client (for protocol calls) and the fetch spy (for
+ * verifying outgoing HTTP requests when needed).
+ */
+async function bootMcpPair(opts: { capabilities: string[]; routes?: Record<string, unknown> }) {
+  const allRoutes: Record<string, unknown> = {
+    '/v1/auth/introspect': introspectionResponse(opts.capabilities),
+    ...opts.routes,
+  };
+  const fetchSpy = makeFetchRouter(allRoutes);
+  vi.stubGlobal('fetch', fetchSpy);
+
+  // Arrange -- Taiga client, introspect, register tools
+  const taigaClient = new TaigaClient({
+    baseUrl: 'https://api.test.com',
+    apiKey: 'taiga_sk_live_test',
+  });
+  await taigaClient.introspect();
+
+  const server = new McpServer({ name: 'taiga-test', version: '0.0.1' });
+  registerAllTools(server, taigaClient);
+
+  const client = new Client({ name: 'test-client', version: '0.0.1' });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+
+  return { client, fetchSpy };
+}
+
+/** Extract sorted tool names from a listTools response. */
+function toolNames(tools: { name: string }[]) {
+  return tools.map((t) => t.name).sort();
+}
+
+/** Extract parsed JSON from the first text content block of a tool call result. */
+function parseToolResult(result: Record<string, unknown>) {
+  const content = result.content as { type: string; text: string }[];
+  return JSON.parse(content[0].text);
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('MCP server integration', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool discovery -- the AI assistant asks "what tools do you have?"
+  // These tests verify the server exposes exactly the right tools based on
+  // the API key's capabilities. This is the primary security contract.
+  // -------------------------------------------------------------------------
+
+  describe('tool discovery', () => {
+    it('should expose all 11 tools when API key has full capabilities', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const { tools } = await client.listTools();
+
+      expect(toolNames(tools)).toEqual(ALL_TOOL_NAMES);
+    });
+
+    it('should reject tools/list when API key has no capabilities', async () => {
+      // When zero tools are registered, the MCP SDK doesn't advertise
+      // the tools capability at all -- the protocol-correct response
+      // is "Method not found".
+      const { client } = await bootMcpPair({ capabilities: [] });
+
+      await expect(client.listTools()).rejects.toThrow(/Method not found/);
+    });
+
+    it('should expose only project tools for a projects:read-only key', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['projects:read'] });
+
+      const { tools } = await client.listTools();
+      const names = toolNames(tools);
+
+      expect(names).toContain('taiga_list_projects');
+      expect(names).toContain('taiga_get_project');
+      expect(names).toContain('taiga_list_environments');
+      expect(names).not.toContain('taiga_list_teams');
+      expect(names).not.toContain('taiga_list_documents');
+    });
+
+    it('should expose read-only document tools without write capability', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['tenant:documents:read'] });
+
+      const { tools } = await client.listTools();
+      const names = toolNames(tools);
+
+      expect(names).toContain('taiga_list_documents');
+      expect(names).toContain('taiga_get_document');
+      expect(names).toContain('taiga_list_skills');
+      expect(names).toContain('taiga_get_skill');
+      expect(names).not.toContain('taiga_update_document');
+    });
+
+    it('should expose update tool when documents:write is also granted', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['tenant:documents:read', 'tenant:documents:write'],
+      });
+
+      const { tools } = await client.listTools();
+
+      expect(toolNames(tools)).toContain('taiga_update_document');
+    });
+
+    it('should expose backlog tools only with backlog:read', async () => {
+      const { client } = await bootMcpPair({ capabilities: ['backlog:read'] });
+
+      const { tools } = await client.listTools();
+      const names = toolNames(tools);
+
+      expect(names).toContain('taiga_list_backlog_items');
+      expect(names).toContain('taiga_get_backlog_item');
+      expect(names).not.toContain('taiga_list_environments');
+    });
+
+    it('should combine capabilities additively', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ['projects:read', 'backlog:read'],
+      });
+
+      const { tools } = await client.listTools();
+      const names = toolNames(tools);
+
+      // projects:read tools present
+      expect(names).toContain('taiga_list_projects');
+      expect(names).toContain('taiga_list_environments');
+      // backlog:read tools present
+      expect(names).toContain('taiga_list_backlog_items');
+      // unrelated capabilities absent
+      expect(names).not.toContain('taiga_list_documents');
+      expect(names).not.toContain('taiga_list_teams');
+    });
+
+    it('should provide a description and input schema for every tool', async () => {
+      const { client } = await bootMcpPair({ capabilities: ALL_CAPABILITIES });
+
+      const { tools } = await client.listTools();
+
+      for (const tool of tools) {
+        expect(tool.description, `${tool.name} missing description`).toBeTruthy();
+        expect(tool.inputSchema, `${tool.name} missing inputSchema`).toBeDefined();
+        expect(tool.inputSchema.type).toBe('object');
+      }
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Capability-tool contract -- parametric tests proving each capability
+  // maps to exactly the right set of tools. If someone adds a tool but
+  // forgets the capability check, these tests catch it.
+  // -------------------------------------------------------------------------
+
+  describe('capability-tool contract', () => {
+    const CONTRACT: Record<string, string[]> = {
+      'projects:read': ['taiga_list_projects', 'taiga_get_project', 'taiga_list_environments'],
+      'teams:read': ['taiga_list_teams'],
+      'tenant:documents:read': ['taiga_list_documents', 'taiga_get_document', 'taiga_list_skills', 'taiga_get_skill'],
+      'tenant:documents:write': ['taiga_update_document'],
+      'backlog:read': ['taiga_list_backlog_items', 'taiga_get_backlog_item'],
+    };
+
+    for (const [capability, expectedTools] of Object.entries(CONTRACT)) {
+      it(`${capability} should gate: ${expectedTools.join(', ')}`, async () => {
+        const { client } = await bootMcpPair({ capabilities: [capability] });
+
+        const { tools } = await client.listTools();
+        const names = toolNames(tools);
+
+        for (const expected of expectedTools) {
+          expect(names, `Expected ${expected} for ${capability}`).toContain(expected);
+        }
+      });
+    }
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool execution -- the AI assistant calls a tool and gets data back.
+  // These test the full round-trip: MCP call -> tool handler -> TaigaClient
+  // -> (mocked) API -> response back through MCP protocol.
+  // -------------------------------------------------------------------------
+
+  describe('tool execution', () => {
+    it('should return project list as JSON text content', async () => {
+      const projects = [
+        { id: 'p1', name: 'Alpha' },
+        { id: 'p2', name: 'Beta' },
+      ];
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { 'GET /v1/projects': { data: projects, nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_projects', arguments: {} });
+
+      expect(result.content).toHaveLength(1);
+      expect(parseToolResult(result)).toEqual(projects);
+    });
+
+    it('should pass project id through to the API', async () => {
+      const projectId = '00000000-0000-0000-0000-000000000001';
+      const project = { id: projectId, name: 'Alpha', status: 'active' };
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`GET /v1/projects/${projectId}`]: { data: project } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_get_project',
+        arguments: { id: projectId },
+      });
+
+      expect(parseToolResult(result)).toEqual(project);
+    });
+
+    it('should return document content through MCP protocol', async () => {
+      const docs = [{ id: 'd1', title: 'Security Policy' }];
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { 'GET /v1/tenants/current/documents': { data: docs, nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_documents', arguments: {} });
+
+      expect(parseToolResult(result)).toEqual(docs);
+    });
+
+    it('should send PUT when updating a document draft', async () => {
+      const docType = 'security_policy';
+      const updated = { type: docType, title: 'Updated Policy' };
+
+      const { client, fetchSpy } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`PUT /v1/tenants/current/documents/${docType}/draft`]: { data: updated } },
+      });
+
+      await client.callTool({
+        name: 'taiga_update_document',
+        arguments: { type: docType, data: { title: 'Updated' } },
+      });
+
+      const putCall = fetchSpy.mock.calls.find((c: unknown[]) => (c[1] as RequestInit)?.method === 'PUT');
+      expect(putCall).toBeDefined();
+      expect(putCall![0]).toContain(`/v1/tenants/current/documents/${docType}/draft`);
+    });
+
+    it('should pass projectId to backlog items endpoint', async () => {
+      const projectId = '00000000-0000-0000-0000-000000000001';
+      const items = [{ id: 'bi1', name: 'Feature X' }];
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { [`GET /v1/projects/${projectId}/backlog`]: { data: items, nextCursor: null } },
+      });
+
+      const result = await client.callTool({
+        name: 'taiga_list_backlog_items',
+        arguments: { projectId },
+      });
+
+      expect(parseToolResult(result)).toEqual(items);
+    });
+
+    it('should return skills through MCP protocol', async () => {
+      const skills = [{ id: 's1', name: 'React Standards' }];
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { 'GET /v1/agent-skills': { data: skills, nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_skills', arguments: {} });
+
+      expect(parseToolResult(result)).toEqual(skills);
+    });
+
+    it('should return teams through MCP protocol', async () => {
+      const teams = [{ id: 't1', name: 'Engineering' }];
+
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: { 'GET /v1/teams': { data: teams, nextCursor: null } },
+      });
+
+      const result = await client.callTool({ name: 'taiga_list_teams', arguments: {} });
+
+      expect(parseToolResult(result)).toEqual(teams);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error handling -- when the API fails, the AI assistant should get a
+  // clear error, not a silent success or cryptic crash.
+  // -------------------------------------------------------------------------
+
+  describe('error handling', () => {
+    it('should surface API errors as MCP error content', async () => {
+      // Introspect succeeds, but all other endpoints fail
+      const fetchSpy = vi.fn().mockImplementation(async (url: string) => {
+        const path = new URL(url).pathname;
+        if (path === '/v1/auth/introspect') {
+          return {
+            ok: true,
+            status: 200,
+            json: () => Promise.resolve(introspectionResponse(ALL_CAPABILITIES)),
+            text: () => Promise.resolve(''),
+          };
+        }
+        return {
+          ok: false,
+          status: 500,
+          json: () => Promise.resolve({ error: 'Internal Server Error' }),
+          text: () => Promise.resolve('Internal Server Error'),
+        };
+      });
+      vi.stubGlobal('fetch', fetchSpy);
+
+      // Arrange
+      const taigaClient = new TaigaClient({ baseUrl: 'https://api.test.com', apiKey: 'test' });
+      await taigaClient.introspect();
+      const server = new McpServer({ name: 'test', version: '0.0.1' });
+      registerAllTools(server, taigaClient);
+      const mcpClient = new Client({ name: 'test-client', version: '0.0.1' });
+      const [ct, st] = InMemoryTransport.createLinkedPair();
+      await Promise.all([server.connect(st), mcpClient.connect(ct)]);
+
+      // Act
+      const result = await mcpClient.callTool({ name: 'taiga_list_projects', arguments: {} });
+
+      // Assert -- the MCP SDK marks tool errors with isError
+      expect(result.isError).toBe(true);
+    });
+
+    it('should reject tool calls with invalid parameters', async () => {
+      const { client } = await bootMcpPair({
+        capabilities: ALL_CAPABILITIES,
+        routes: {},
+      });
+
+      // taiga_get_project requires a UUID, not a plain string
+      const result = await client.callTool({
+        name: 'taiga_get_project',
+        arguments: { id: 'not-a-uuid' },
+      });
+
+      expect(result.isError).toBe(true);
+    });
+  });
+});

package/src/tools/backlogs.ts

@@ -0,0 +1,53 @@
+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) }],
+        };
+      }
+    );
+  }
+}

package/src/tools/documents.ts

@@ -0,0 +1,55 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { TaigaClient } from '../client.js';
+
+export function registerDocumentTools(server: McpServer, client: TaigaClient) {
+  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.',
+      {
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      async (params) => {
+        const result = await client.listTenantDocuments(params);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, 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.',
+      {
+        type: z.string().describe('Document type (e.g. security_policy, sdlc_policy)'),
+      },
+      async (params) => {
+        const result = await client.getTenantDocument(params.type);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+
+  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.',
+      {
+        type: z.string().describe('Document type (e.g. security_policy)'),
+        data: z.record(z.string(), z.unknown()).describe('Document content to save'),
+      },
+      async (params) => {
+        const { type, ...body } = params;
+        const result = await client.saveTenantDocumentDraft(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

@@ -0,0 +1,18 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TaigaClient } from '../client.js';
+import { registerProjectTools } from './projects.js';
+import { registerDocumentTools } from './documents.js';
+import { registerBacklogTools } from './backlogs.js';
+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.
+ */
+export function registerAllTools(server: McpServer, client: TaigaClient): void {
+  registerProjectTools(server, client);
+  registerDocumentTools(server, client);
+  registerBacklogTools(server, client);
+  registerSkillTools(server, client);
+}

package/src/tools/projects.ts

@@ -0,0 +1,53 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { TaigaClient } from '../client.js';
+
+export function registerProjectTools(server: McpServer, client: TaigaClient) {
+  if (client.hasCapability('projects:read')) {
+    server.tool(
+      'taiga_list_projects',
+      'List all projects in the organization. Returns project name, status, team, and metadata.',
+      {
+        teamId: z.string().uuid().optional().describe('Filter by team ID'),
+        status: z.enum(['draft', 'active', 'archived']).optional().describe('Filter by status'),
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      async (params) => {
+        const result = await client.listProjects(params);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+
+    server.tool(
+      'taiga_get_project',
+      'Get detailed information about a specific project by ID.',
+      {
+        id: z.string().uuid().describe('Project ID'),
+      },
+      async (params) => {
+        const result = await client.getProject(params.id);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+
+  if (client.hasCapability('teams:read')) {
+    server.tool(
+      'taiga_list_teams',
+      'List all teams in the organization.',
+      {
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      async (params) => {
+        const result = await client.listTeams(params);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+}

package/src/tools/skills.ts

@@ -0,0 +1,39 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import type { TaigaClient } from '../client.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).',
+      {
+        limit: z.number().min(1).max(100).optional().describe('Max results (default 25)'),
+      },
+      async (params) => {
+        const result = await client.listSkills(params);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, 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.',
+      {
+        id: z.string().uuid().describe('Skill ID'),
+      },
+      async (params) => {
+        const result = await client.getSkill(params.id);
+        return {
+          content: [{ type: 'text' as const, text: JSON.stringify(result.data, null, 2) }],
+        };
+      }
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "declarationMap": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    environment: 'node',
+    testTimeout: 10_000,
+  },
+});