@taiga-ai/mcp-server 0.4.0-rc.345 → 0.5.0-dev.388

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taiga-ai/mcp-server",
-  "version": "0.4.0-rc.345",
+  "version": "0.5.0-dev.388",
   "description": "MCP server for Taiga -- gives AI assistants access to documents and products",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,6 @@
   "scripts": {
     "build": "tsc --noEmit && node scripts/build.mjs",
     "typecheck": "tsc --noEmit",
-    "dev": "tsc --watch",
     "lint": "oxlint src",
     "format": "oxfmt --check \"**/*.{ts,tsx,js,jsx,mjs,cjs,json,md}\"",
     "format:fix": "oxfmt \"**/*.{ts,tsx,js,jsx,mjs,cjs,json,md}\"",
@@ -27,6 +26,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@tsconfig/strictest": "^2.0.8",
     "@types/node": "^22.20.1",
     "rolldown": "^1.2.3",
     "typescript": "^7.0.2",

package/src/client.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { readFileSync } from 'node:fs';
-import { TaigaClient } from './client.js';
+import { TaigaApiError, TaigaClient } from './client.js';
 
 // Read independently of src/version.ts, so the test checks the real file.
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string };
@@ -57,7 +57,7 @@ describe('TaigaClient', () => {
       await client.listProducts();
 
       // Assert
-      const headers = spy.mock.calls[0][1].headers;
+      const headers = spy.mock.calls[0]![1].headers;
       expect(headers.Authorization).toBe('Bearer taiga_sk_live_secret42');
     });
 
@@ -66,7 +66,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listProducts();
 
-      expect(spy.mock.calls[0][1].headers['User-Agent']).toBe(`taiga-ai-mcp-server/${pkg.version}`);
+      expect(spy.mock.calls[0]![1].headers['User-Agent']).toBe(`taiga-ai-mcp-server/${pkg.version}`);
     });
   });
 
@@ -113,7 +113,7 @@ describe('TaigaClient', () => {
 
       await client.listProducts();
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/products');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/products');
     });
 
     it('should omit query string when no optional params are provided', async () => {
@@ -121,7 +121,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listProducts();
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/products');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/products');
     });
 
     it('should include all optional filters as query params', async () => {
@@ -129,7 +129,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listProducts({ factoryId: 't1', status: 'active', limit: 10 });
 
-      const url = spy.mock.calls[0][0] as string;
+      const url = spy.mock.calls[0]![0] as string;
       expect(url).toContain('factoryId=t1');
       expect(url).toContain('status=active');
       expect(url).toContain('limit=10');
@@ -140,7 +140,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listBacklogItems('proj-1', { limit: 20 });
 
-      const url = spy.mock.calls[0][0] as string;
+      const url = spy.mock.calls[0]![0] as string;
       expect(url).toContain('/v1/products/proj-1/backlog');
       expect(url).toContain('limit=20');
     });
@@ -150,7 +150,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listEnvironments('proj-1');
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/products/proj-1/environments');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/products/proj-1/environments');
     });
   });
 
@@ -211,7 +211,7 @@ describe('TaigaClient', () => {
 
       const result = await makeClient().getProduct('p1');
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/products/p1');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/products/p1');
       expect(result.data).toEqual({ id: 'p1', name: 'Alpha' });
     });
 
@@ -220,7 +220,7 @@ describe('TaigaClient', () => {
 
       await makeClient().getTenantDocument('security_policy');
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/tenants/current/documents/security_policy');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/tenants/current/documents/security_policy');
     });
 
     it('should PUT a document draft with the provided body', async () => {
@@ -228,11 +228,73 @@ describe('TaigaClient', () => {
 
       await makeClient().saveTenantDocumentDraft('security_policy', { data: { title: 'New' } });
 
-      expect(spy.mock.calls[0][1].method).toBe('PUT');
-      expect(spy.mock.calls[0][0]).toContain('/tenants/current/documents/security_policy/draft');
-      expect(JSON.parse(spy.mock.calls[0][1].body)).toEqual({
+      expect(spy.mock.calls[0]![1].method).toBe('PUT');
+      expect(spy.mock.calls[0]![0]).toContain('/tenants/current/documents/security_policy/draft');
+      expect(JSON.parse(spy.mock.calls[0]![1].body)).toEqual({
         data: { title: 'New' },
       });
+      expect(spy.mock.calls[0]![1].headers['Content-Type']).toBe('application/json');
+    });
+
+    it('should keep every path segment inside its route', async () => {
+      const spy = stubFetch(200, { data: {} });
+      const client = makeClient();
+
+      await client.getTenantDocument('../products/x');
+      await client.getFactoryDocument('f/1', 'a b');
+      await client.getProduct('p/1');
+      await client.getBacklogItem('b/1');
+      await client.listEnvironments('e/1');
+      await client.getProductDocument('p/1', 'spec/x');
+
+      const paths = spy.mock.calls.map((c) => new URL(c[0] as string).pathname);
+      expect(paths).toEqual([
+        '/v1/tenants/current/documents/..%2Fproducts%2Fx',
+        '/v1/factories/f%2F1/documents/a%20b',
+        '/v1/products/p%2F1',
+        '/v1/backlog/b%2F1',
+        '/v1/products/e%2F1/environments',
+        '/v1/products/p%2F1/documents/spec%2Fx',
+      ]);
+    });
+
+    it('should refuse the dot segments encodeURIComponent cannot neutralise', async () => {
+      // `/documents/../publish` would collapse to `/tenants/current/publish`.
+      const spy = stubFetch(200, { data: {} });
+      const client = makeClient();
+
+      await expect(client.publishTenantDocument('..')).rejects.toThrow(/Invalid path segment/);
+      await expect(client.getTenantDocumentDraft('.')).rejects.toThrow(/Invalid path segment/);
+      await expect(client.getTenantDocument('')).rejects.toThrow(/Invalid path segment/);
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it('should POST a publish with no body and no JSON content type', async () => {
+      // Fastify answers 400 "Body cannot be empty" to a JSON content type
+      // without a body, which is what the publish routes would otherwise get.
+      const spy = stubFetch(200, { data: { id: 'd1', version: 2 } });
+
+      await makeClient().publishTenantDocument('policy_security');
+
+      expect(spy.mock.calls[0]![1].method).toBe('POST');
+      expect(spy.mock.calls[0]![0]).toContain('/tenants/current/documents/policy_security/publish');
+      expect(spy.mock.calls[0]![1].body).toBeNull();
+      expect(spy.mock.calls[0]![1].headers).not.toHaveProperty('Content-Type');
+    });
+
+    it('should expose the API status, code and message on a failed request', async () => {
+      stubFetch(400, { error: 'Bad Request', code: 'VALIDATION_ERROR', message: 'Draft contains template residue' });
+
+      const error = await makeClient()
+        .publishTenantDocument('policy_security')
+        .catch((e: unknown) => e as TaigaApiError);
+
+      expect(error).toBeInstanceOf(TaigaApiError);
+      expect(error).toMatchObject({
+        status: 400,
+        code: 'VALIDATION_ERROR',
+        apiMessage: 'Draft contains template residue',
+      });
     });
 
     it('should GET a single backlog item by id (flat path)', async () => {
@@ -240,7 +302,7 @@ describe('TaigaClient', () => {
 
       await makeClient().getBacklogItem('item-1');
 
-      expect(spy.mock.calls[0][0]).toBe('https://api.test.com/v1/backlog/item-1');
+      expect(spy.mock.calls[0]![0]).toBe('https://api.test.com/v1/backlog/item-1');
     });
 
     it('should GET factories with optional limit', async () => {
@@ -248,7 +310,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listFactories({ limit: 50 });
 
-      expect(spy.mock.calls[0][0]).toContain('/v1/factories?limit=50');
+      expect(spy.mock.calls[0]![0]).toContain('/v1/factories?limit=50');
     });
 
     it('should GET documents from tenant path with optional limit', async () => {
@@ -256,7 +318,7 @@ describe('TaigaClient', () => {
 
       await makeClient().listTenantDocuments({ limit: 5 });
 
-      expect(spy.mock.calls[0][0]).toContain('/v1/tenants/current/documents?limit=5');
+      expect(spy.mock.calls[0]![0]).toContain('/v1/tenants/current/documents?limit=5');
     });
   });
 });

package/src/client.ts

@@ -1,6 +1,78 @@
 import type { ApiKeyIntrospection } from '@taiga/types';
 import { SERVER_VERSION } from './version.js';
 
+/**
+ * A non-2xx answer from the Taiga API. Carries the status and the API's own
+ * `code` and `message` so a tool can hand the model something it can act on
+ * (a 400 from the publish gate names the section that still holds template
+ * residue) instead of one opaque string.
+ */
+export class TaigaApiError extends Error {
+  readonly status: number;
+  readonly code: string | undefined;
+  readonly apiMessage: string | undefined;
+
+  constructor(method: string, path: string, status: number, body: string) {
+    const parsed = parseErrorBody(body);
+    super(`Taiga API ${method} ${path} failed (${status}): ${parsed.message ?? body}`);
+    this.name = 'TaigaApiError';
+    this.status = status;
+    this.code = parsed.code;
+    this.apiMessage = parsed.message;
+  }
+}
+
+/**
+ * One path segment. Every id and type a tool passes is validated at the
+ * tool boundary; this is the second wall. Encoding keeps a slash inside the
+ * segment, and the dot segments are refused outright: encodeURIComponent
+ * leaves "." and ".." as they are, and the URL parser in fetch would then
+ * collapse `/documents/../publish` into a different route.
+ */
+function seg(value: string): string {
+  if (value === '' || value === '.' || value === '..') {
+    throw new TypeError(`Invalid path segment: ${JSON.stringify(value)}`);
+  }
+  return encodeURIComponent(value);
+}
+
+function parseErrorBody(body: string): { code?: string; message?: string } {
+  try {
+    const json = JSON.parse(body) as { code?: unknown; message?: unknown; details?: unknown };
+    const message = typeof json.message === 'string' ? json.message : undefined;
+    // A 400 from route validation says only "Request validation failed";
+    // the field and the reason are in `details`, and the model needs them.
+    const details = Array.isArray(json.details)
+      ? json.details
+          .map((d: { instancePath?: unknown; message?: unknown }) =>
+            [d.instancePath, d.message].filter((x) => typeof x === 'string' && x).join(' ')
+          )
+          .filter(Boolean)
+      : [];
+    return {
+      ...(typeof json.code === 'string' ? { code: json.code } : {}),
+      ...(message ? { message: details.length ? `${message}: ${details.join('; ')}` : message } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A tenant or factory document as the API returns it: the fields the tools
+ * read. `data` holds the content; policies and instructions keep it under
+ * `sections` (see tools/sections.ts).
+ */
+export interface TaigaDocument {
+  id: string;
+  type: string;
+  name: string;
+  version: number | null;
+  isDraft: boolean;
+  data: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
 /**
  * HTTP client for the Taiga API.
  * Used by the MCP server to proxy tool calls to the backend.
@@ -19,19 +91,21 @@ export class TaigaClient {
     const url = `${this.baseUrl}/v1${path}`;
     const headers: Record<string, string> = {
       Authorization: `Bearer ${this.apiKey}`,
-      'Content-Type': 'application/json',
       'User-Agent': `taiga-ai-mcp-server/${SERVER_VERSION}`,
     };
+    // Only with a body: Fastify refuses an empty body under a JSON
+    // content type, which is what a bodiless POST (publish) would send.
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
 
     const response = await fetch(url, {
       method,
       headers,
-      body: body ? JSON.stringify(body) : undefined,
+      body: body === undefined ? null : JSON.stringify(body),
     });
 
     if (!response.ok) {
       const text = await response.text().catch(() => '');
-      throw new Error(`Taiga API ${method} ${path} failed (${response.status}): ${text}`);
+      throw new TaigaApiError(method, path, response.status, text);
     }
 
     return response.json() as Promise<T>;
@@ -60,7 +134,11 @@ export class TaigaClient {
   // Products
   // ---------------------------------------------------------------------------
 
-  async listProducts(opts?: { factoryId?: string; status?: string; limit?: number }) {
+  async listProducts(opts?: {
+    factoryId?: string | undefined;
+    status?: string | undefined;
+    limit?: number | undefined;
+  }) {
     const params = new URLSearchParams();
     if (opts?.factoryId) params.set('factoryId', opts.factoryId);
     if (opts?.status) params.set('status', opts.status);
@@ -70,14 +148,14 @@ export class TaigaClient {
   }
 
   async getProduct(id: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${id}`);
+    return this.request<{ data: unknown }>('GET', `/products/${seg(id)}`);
   }
 
   // ---------------------------------------------------------------------------
   // Documents (tenant-level policies)
   // ---------------------------------------------------------------------------
 
-  async listTenantDocuments(opts?: { limit?: number }) {
+  async listTenantDocuments(opts?: { limit?: number | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();
@@ -88,51 +166,76 @@ export class TaigaClient {
   }
 
   async getTenantDocument(type: string) {
-    return this.request<{ data: unknown }>('GET', `/tenants/current/documents/${type}`);
+    return this.request<{ data: TaigaDocument }>('GET', `/tenants/current/documents/${seg(type)}`);
+  }
+
+  /** The shared draft for a document type, or `{ data: null }` when none exists. */
+  async getTenantDocumentDraft(type: string) {
+    return this.request<{ data: TaigaDocument | null }>('GET', `/tenants/current/documents/${seg(type)}/draft`);
   }
 
   async saveTenantDocumentDraft(type: string, body: { data: Record<string, unknown> }) {
-    return this.request<{ data: unknown }>('PUT', `/tenants/current/documents/${type}/draft`, body);
+    return this.request<{ data: TaigaDocument }>('PUT', `/tenants/current/documents/${seg(type)}/draft`, body);
+  }
+
+  async publishTenantDocument(type: string) {
+    return this.request<{ data: TaigaDocument }>('POST', `/tenants/current/documents/${seg(type)}/publish`);
   }
 
   // ---------------------------------------------------------------------------
   // Factory Documents
   // ---------------------------------------------------------------------------
 
-  async listFactoryDocuments(factoryId: string, opts?: { limit?: number }) {
+  async listFactoryDocuments(factoryId: string, opts?: { limit?: number | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
-      `/factories/${factoryId}/documents${qs ? `?${qs}` : ''}`
+      `/factories/${seg(factoryId)}/documents${qs ? `?${qs}` : ''}`
     );
   }
 
   async getFactoryDocument(factoryId: string, type: string) {
-    return this.request<{ data: unknown }>('GET', `/factories/${factoryId}/documents/${type}`);
+    return this.request<{ data: TaigaDocument }>('GET', `/factories/${seg(factoryId)}/documents/${seg(type)}`);
+  }
+
+  /** The shared draft for a factory document type, or `{ data: null }` when none exists. */
+  async getFactoryDocumentDraft(factoryId: string, type: string) {
+    return this.request<{ data: TaigaDocument | null }>(
+      'GET',
+      `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`
+    );
   }
 
   async saveFactoryDocumentDraft(factoryId: string, type: string, body: { data: Record<string, unknown> }) {
-    return this.request<{ data: unknown }>('PUT', `/factories/${factoryId}/documents/${type}/draft`, body);
+    return this.request<{ data: TaigaDocument }>(
+      'PUT',
+      `/factories/${seg(factoryId)}/documents/${seg(type)}/draft`,
+      body
+    );
+  }
+
+  async publishFactoryDocument(factoryId: string, type: string) {
+    return this.request<{ data: TaigaDocument }>('POST', `/factories/${seg(factoryId)}/documents/${seg(type)}/publish`);
   }
 
   // ---------------------------------------------------------------------------
   // Product Documents
   // ---------------------------------------------------------------------------
 
-  async listProductDocuments(productId: string, opts?: { limit?: number }) {
+  async listProductDocuments(productId: string, opts?: { limit?: number | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
-      `/products/${productId}/documents${qs ? `?${qs}` : ''}`
+      `/products/${seg(productId)}/documents${qs ? `?${qs}` : ''}`
     );
   }
 
   async getProductDocument(productId: string, type: string) {
-    return this.request<{ data: unknown }>('GET', `/products/${productId}/documents/${type}`);
+    return this.request<{ data: unknown }>('GET', `/products/${seg(productId)}/documents/${seg(type)}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -146,7 +249,7 @@ export class TaigaClient {
    */
   async getProductContext(productId: string): Promise<Record<string, unknown>> {
     // First fetch the product to get its factory
-    const product = await this.request<{ data: Record<string, unknown> }>('GET', `/products/${productId}`);
+    const product = await this.request<{ data: Record<string, unknown> }>('GET', `/products/${seg(productId)}`);
     const factoryId = product.data.factoryId as string | undefined;
 
     // Fetch the document lists in parallel.
@@ -214,18 +317,18 @@ export class TaigaClient {
   // Backlog
   // ---------------------------------------------------------------------------
 
-  async listBacklogItems(productId: string, opts?: { limit?: number }) {
+  async listBacklogItems(productId: string, opts?: { limit?: number | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();
     return this.request<{ data: unknown[]; nextCursor: string | null }>(
       'GET',
-      `/products/${productId}/backlog${qs ? `?${qs}` : ''}`
+      `/products/${seg(productId)}/backlog${qs ? `?${qs}` : ''}`
     );
   }
 
   async getBacklogItem(itemId: string) {
-    return this.request<{ data: unknown }>('GET', `/backlog/${itemId}`);
+    return this.request<{ data: unknown }>('GET', `/backlog/${seg(itemId)}`);
   }
 
   // ---------------------------------------------------------------------------
@@ -233,14 +336,14 @@ export class TaigaClient {
   // ---------------------------------------------------------------------------
 
   async listEnvironments(productId: string) {
-    return this.request<{ data: unknown[] }>('GET', `/products/${productId}/environments`);
+    return this.request<{ data: unknown[] }>('GET', `/products/${seg(productId)}/environments`);
   }
 
   // ---------------------------------------------------------------------------
   // Factories
   // ---------------------------------------------------------------------------
 
-  async listFactories(opts?: { limit?: number }) {
+  async listFactories(opts?: { limit?: number | undefined }) {
     const params = new URLSearchParams();
     if (opts?.limit) params.set('limit', String(opts.limit));
     const qs = params.toString();

package/src/config.test.ts

@@ -0,0 +1,24 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { readConfig } from './config.js';
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('readConfig', () => {
+  it('needs an API key', () => {
+    vi.stubEnv('TAIGA_API_KEY', undefined);
+    expect(readConfig()).toBeNull();
+    vi.stubEnv('TAIGA_API_KEY', '');
+    expect(readConfig()).toBeNull();
+  });
+
+  it('defaults the API URL', () => {
+    vi.stubEnv('TAIGA_API_KEY', 'taiga_sk_live_test');
+    vi.stubEnv('TAIGA_API_URL', undefined);
+    expect(readConfig()).toEqual({ apiKey: 'taiga_sk_live_test', apiUrl: 'https://api.taiga.app' });
+    vi.stubEnv('TAIGA_API_URL', 'http://localhost:3001');
+    expect(readConfig()?.apiUrl).toBe('http://localhost:3001');
+  });
+});

package/src/config.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/**
+ * The one place the MCP server reads its environment (PRO-2511), parsed once
+ * at startup.
+ */
+
+const DEFAULT_API_URL = 'https://api.taiga.app';
+
+const envSchema = z.object({
+  TAIGA_API_KEY: z.string().min(1),
+  TAIGA_API_URL: z.string().default(DEFAULT_API_URL),
+});
+
+export interface ServerConfig {
+  readonly apiKey: string;
+  readonly apiUrl: string;
+}
+
+/** Null when TAIGA_API_KEY is missing or empty: it is the one setting with no default. */
+export function readConfig(): ServerConfig | null {
+  const parsed = envSchema.safeParse(process.env);
+  if (!parsed.success) return null;
+  return { apiKey: parsed.data.TAIGA_API_KEY, apiUrl: parsed.data.TAIGA_API_URL };
+}

package/src/index.ts

@@ -3,22 +3,19 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TaigaClient } from './client.js';
+import { readConfig } from './config.js';
 import { registerAllTools } from './tools/index.js';
 import { SERVER_VERSION } from './version.js';
 
-const DEFAULT_API_URL = 'https://api.taiga.app';
-
 async function main() {
-  const apiKey = process.env.TAIGA_API_KEY;
-  if (!apiKey) {
+  const config = readConfig();
+  if (!config) {
     console.error('Error: TAIGA_API_KEY environment variable is required.');
     console.error('Create an API key at https://app.taiga.app/settings/api-keys');
     process.exit(1);
   }
 
-  const apiUrl = process.env.TAIGA_API_URL ?? DEFAULT_API_URL;
-
-  const client = new TaigaClient({ baseUrl: apiUrl, apiKey });
+  const client = new TaigaClient({ baseUrl: config.apiUrl, apiKey: config.apiKey });
 
   // Introspect the API key to discover available capabilities
   const introspection = await client.introspect().catch((error) => {
@@ -55,8 +52,9 @@ async function main() {
         'For product-specific work, use taiga_list_products to find the product,',
         'then read its specification and architecture.',
         '',
-        'When you notice a policy or factory instructions are outdated, use the update tools',
-        '(taiga_update_document, taiga_update_factory_document) to fix it.',
+        'When you notice a policy or factory instructions are outdated, fix the section with',
+        'taiga_update_document or taiga_update_factory_document. That saves a draft nobody follows yet;',
+        'publish it with taiga_publish_document or taiga_publish_factory_document only when the person asks.',
         'This keeps the knowledge base accurate for everyone.',
       ].join('\n'),
     }