@taiga-ai/mcp-server 0.8.0-dev.397 → 0.9.0-rc.403

package/src/tools/resources.ts

@@ -0,0 +1,216 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, type ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
+import { TaigaApiError, type TaigaClient } from '../client.js';
+import { RequestError, apiFailureText, isMissOrRefusal } from './errors.js';
+import {
+  FACTORY_DOCUMENT_TYPES,
+  PRODUCT_DOCUMENT_ORIGINS,
+  PRODUCT_DOCUMENT_TYPES,
+  TENANT_DOCUMENT_TYPES,
+  defaultOriginFor,
+  productDocumentName,
+  type ProductDocumentOrigin,
+  type ProductDocumentType,
+  type ProductSettingsView,
+} from './catalogue.js';
+import { productId as productIdInput } from './inputs.js';
+import { mimeTypeOf, renderDocument } from './markdown.js';
+import { stripProvenance } from './sections.js';
+
+/**
+ * The knowledge base as resources, so an IDE can attach a document with `@`
+ * the way it attaches a file. Every resource reads through the same routes
+ * and capability gates as the tool that reads it, and returns the same
+ * stripped content, rendered as Markdown where the document is a section
+ * map. `resources/list` names what is published; the templates say how to
+ * address the rest.
+ *
+ * A resource has no `isError` result: a refusal or a miss is a JSON-RPC
+ * error, InvalidParams (the caller named something that does not exist)
+ * with a message that says what does.
+ */
+
+/** One text resource, rendered. */
+function contents(uri: string, doc: Record<string, unknown>): ReadResourceResult {
+  const rendered = renderDocument(stripProvenance(doc));
+  return { contents: [{ uri, mimeType: rendered.mimeType, text: rendered.text }] };
+}
+
+function invalid(message: string): never {
+  throw new RequestError(ErrorCode.InvalidParams, message);
+}
+
+function requireOneOf<T extends string>(what: string, value: string, allowed: readonly T[]): T {
+  if (!(allowed as readonly string[]).includes(value))
+    invalid(`${what} "${value}" is not one of: ${allowed.join(', ')}`);
+  return value as T;
+}
+
+function requireId(what: string, value: string): string {
+  if (!productIdInput.safeParse(value).success) invalid(`${what} "${value}" is not an ID`);
+  return value;
+}
+
+/** The read, with a miss or a refusal turned into guidance; anything else is the API failing and propagates. */
+async function served<T>(read: Promise<T>, miss: string): Promise<T> {
+  try {
+    return await read;
+  } catch (error) {
+    if (!isMissOrRefusal(error)) throw error;
+    return invalid(`${miss} (${apiFailureText(error)})`);
+  }
+}
+
+export function registerResources(server: McpServer, client: TaigaClient) {
+  if (client.hasCapability('tenant:documents:read')) {
+    const published = async () =>
+      ((await client.listTenantDocuments({ limit: 100 })).data as Record<string, unknown>[]).filter(
+        (row) => row.isDraft === false
+      );
+
+    server.registerResource(
+      'organization-document',
+      new ResourceTemplate('taiga://documents/{type}', {
+        // What is published, so the client can offer it without guessing.
+        // A tenant list the API would not serve must not empty every other
+        // resource from the client's picker: this one lists nothing then.
+        list: async () => ({
+          resources: (await published().catch(() => [])).map((row) => ({
+            uri: `taiga://documents/${String(row.type)}`,
+            name: String(row.name ?? row.type),
+            description: typeof row.description === 'string' ? row.description : undefined,
+            mimeType: mimeTypeOf(row),
+          })),
+        }),
+      }),
+      {
+        title: 'Organization document',
+        description:
+          'A published organization document: a policy, the business goals, the design or brand standards, the ' +
+          'tone of voice or the standing instructions. Sections rendered as headings.',
+      },
+      async (uri, variables) => {
+        const type = requireOneOf('Document type', String(variables.type), TENANT_DOCUMENT_TYPES);
+        try {
+          return contents(uri.href, (await client.getTenantDocument(type)).data);
+        } catch (error) {
+          if (!isMissOrRefusal(error)) throw error;
+          // The follow-up list is best effort, but a failed one is said to
+          // have failed, not read as "nothing is published".
+          const rest = await published().then(
+            (rows) => {
+              const names = rows.map((row) => String(row.type));
+              return names.length > 0 ? `Published documents: ${names.join(', ')}.` : 'Nothing is published yet.';
+            },
+            (reason: unknown) =>
+              `The published list could not be read (${reason instanceof TaigaApiError ? apiFailureText(reason) : 'the request failed'}).`
+          );
+          return invalid(`No published ${type} the key can read (${apiFailureText(error)}). ${rest}`);
+        }
+      }
+    );
+  }
+
+  if (client.hasCapability('factories:read')) {
+    server.registerResource(
+      'factory-instructions',
+      new ResourceTemplate('taiga://factories/{factoryId}/instructions', { list: undefined }),
+      {
+        title: 'Factory instructions',
+        description:
+          "A factory's published standing guidance; taiga_list_factories gives the factory ID. Markdown for a " +
+          'section map, JSON otherwise (the read says which).',
+      },
+      async (uri, variables) => {
+        const factoryId = requireId('Factory ID', String(variables.factoryId));
+        const doc = await served(
+          client.getFactoryDocument(factoryId, FACTORY_DOCUMENT_TYPES[0]),
+          'This factory has not published instructions, or the key cannot see the factory'
+        );
+        return contents(uri.href, doc.data);
+      }
+    );
+  }
+
+  if (client.hasCapability('products:read')) {
+    const documentType = (value: string): ProductDocumentType => {
+      if (value.includes('?')) invalid(`Name the timeline as ?origin=plan or ?origin=reality, not "${value}"`);
+      return requireOneOf('Document type', value, PRODUCT_DOCUMENT_TYPES);
+    };
+    const read = async (uri: URL, productId: string, type: ProductDocumentType, origin: ProductDocumentOrigin) => {
+      const result = await served(
+        client.getProductDocument(productId, type, origin),
+        `No published ${origin} ${type} for this product, or the key cannot see it; taiga_list_product_documents shows what exists`
+      );
+      return contents(uri.href, { name: productDocumentName(type), ...(result.data as Record<string, unknown>) });
+    };
+
+    // The timeline template first: the SDK tries templates in registration
+    // order, and a URI with ?origin= would otherwise bind the query into {type}.
+    server.registerResource(
+      'product-document-on-timeline',
+      new ResourceTemplate('taiga://products/{productId}/documents/{type}{?origin}', { list: undefined }),
+      {
+        title: 'Product document on a timeline',
+        description:
+          'A product document from the named timeline: origin=plan (discovery) or origin=reality (derived from the code). ' +
+          'Markdown for a section map, JSON otherwise (the read says which).',
+      },
+      async (uri, variables) => {
+        const productId = requireId('Product ID', String(variables.productId));
+        const type = documentType(String(variables.type));
+        const origin = requireOneOf('Origin', String(variables.origin), PRODUCT_DOCUMENT_ORIGINS);
+        return read(uri, productId, type, origin);
+      }
+    );
+
+    server.registerResource(
+      'product-document',
+      new ResourceTemplate('taiga://products/{productId}/documents/{type}', { list: undefined }),
+      {
+        title: 'Product document',
+        description:
+          "A product document from the product's own timeline (reality for an imported product, plan otherwise; " +
+          'the documents a person writes are always on the plan side). taiga_list_product_documents shows what ' +
+          'exists; add ?origin=plan or ?origin=reality to read the other side. Markdown for a section map, JSON ' +
+          'otherwise (the read says which).',
+      },
+      async (uri, variables) => {
+        const productId = requireId('Product ID', String(variables.productId));
+        const type = documentType(String(variables.type));
+        const product = (
+          await served(
+            client.getProduct(productId),
+            'No product with that ID the key can see; taiga_list_products shows them'
+          )
+        ).data as ProductSettingsView;
+        return read(uri, productId, type, defaultOriginFor(product, type));
+      }
+    );
+  }
+
+  if (client.hasCapability('backlog:read')) {
+    server.registerResource(
+      'backlog-item',
+      new ResourceTemplate('taiga://backlog/{itemId}', { list: undefined }),
+      {
+        title: 'Backlog item',
+        description:
+          'An initiative in full: description, acceptance criteria, technical context. taiga_list_backlog_items ' +
+          'gives the item ID.',
+        mimeType: 'application/json',
+      },
+      async (uri, variables) => {
+        const itemId = requireId('Backlog item ID', String(variables.itemId));
+        const item = (
+          await served(
+            client.getBacklogItem(itemId),
+            'No backlog item with that ID the key can see; taiga_list_backlog_items shows what exists'
+          )
+        ).data;
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(item, null, 2) }] };
+      }
+    );
+  }
+}