@tacitai/mcp-server 0.1.1 → 0.3.0

package/dist/tools/chronicle.js

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { TacitApiError } from '../client.js';
+import { success, error } from './errors.js';
+export function registerChronicleTools(server, getClient) {
+    server.tool('tacit_chronicle_timeline', 'Query the Chronicle timeline with date range, scope, and text filters.', {
+        from: z.string().optional().describe('RFC 3339 lower bound (inclusive)'),
+        to: z.string().optional().describe('RFC 3339 upper bound (inclusive)'),
+        offset: z.number().int().optional().describe('Pagination offset'),
+        limit: z.number().int().optional().describe('Max results (cap 200)'),
+        scope: z.enum(['all', 'project', 'chapter']).optional().describe('Display scope (default: all)'),
+        chapter_id: z.string().uuid().optional().describe('Required when scope=chapter'),
+        project_id: z.string().uuid().optional().describe('Required when scope=project'),
+        created_by: z.string().optional().describe("Filter by creator ('me' for current user)"),
+        q: z.string().optional().describe('Full-text search filter'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const params = new URLSearchParams();
+            if (args.from)
+                params.set('from', args.from);
+            if (args.to)
+                params.set('to', args.to);
+            if (args.offset !== undefined)
+                params.set('offset', String(args.offset));
+            if (args.limit !== undefined)
+                params.set('limit', String(args.limit));
+            if (args.scope)
+                params.set('scope', args.scope);
+            if (args.chapter_id)
+                params.set('chapter_id', args.chapter_id);
+            if (args.project_id)
+                params.set('project_id', args.project_id);
+            if (args.created_by)
+                params.set('created_by', args.created_by);
+            if (args.q)
+                params.set('q', args.q);
+            const qs = params.toString();
+            const data = await client.request('GET', `/api/v1/chronicle/timeline${qs ? `?${qs}` : ''}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_chronicle_events', 'List recent Chronicle events with optional filters.', {
+        q: z.string().optional().describe('Prefix search filter'),
+        limit: z.number().int().optional().describe('Max results (default 20, cap 100)'),
+        offset: z.number().int().optional().describe('Pagination offset'),
+        created_by: z.string().optional().describe("Filter: 'me' for current user"),
+        full_content: z.boolean().optional().describe('Return full metadata (default: 100-char snippet)'),
+        event_types: z.string().optional().describe('Comma-separated event types to filter'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const params = new URLSearchParams();
+            if (args.q)
+                params.set('q', args.q);
+            if (args.limit !== undefined)
+                params.set('limit', String(args.limit));
+            if (args.offset !== undefined)
+                params.set('offset', String(args.offset));
+            if (args.created_by)
+                params.set('created_by', args.created_by);
+            if (args.full_content !== undefined)
+                params.set('full_content', String(args.full_content));
+            if (args.event_types)
+                params.set('event_types', args.event_types);
+            const qs = params.toString();
+            const data = await client.request('GET', `/api/v1/chronicle/events/recent${qs ? `?${qs}` : ''}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_chronicle_search', 'Search Chronicle events using hybrid BM25+ANN retrieval.', {
+        q: z.string().describe('Search query text'),
+        limit: z.number().int().optional().describe('Max results'),
+        domain: z.string().optional().describe('Domain context for pre-ANN GIN filtering'),
+        hybrid: z.boolean().optional().describe('Use hybrid BM25+ANN search path'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const params = new URLSearchParams();
+            params.set('q', args.q);
+            params.set('source_type', 'CHRONICLE_EVENT');
+            if (args.limit !== undefined)
+                params.set('limit', String(args.limit));
+            if (args.domain)
+                params.set('domain', args.domain);
+            if (args.hybrid !== undefined)
+                params.set('hybrid', String(args.hybrid));
+            const data = await client.request('GET', `/api/v1/search?${params.toString()}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_chronicle_graph', 'Get the Chronicle causal + semantic DAG graph.', {
+        scope: z.string().describe('Graph scope (required)'),
+        limit: z.number().int().optional().describe('Max nodes'),
+        created_by: z.string().optional().describe('Filter by creator'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const params = new URLSearchParams();
+            params.set('scope', args.scope);
+            if (args.limit !== undefined)
+                params.set('limit', String(args.limit));
+            if (args.created_by)
+                params.set('created_by', args.created_by);
+            const data = await client.request('GET', `/api/v1/chronicle/graph?${params.toString()}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_create_event', 'Create a new Chronicle event.', {
+        event_type: z.string().describe('Event type identifier'),
+        raw_payload: z.string().describe('Event content/payload'),
+        project_id: z.string().uuid().optional().describe('Portfolio context'),
+        chapter_id: z.string().uuid().optional().describe('Program context'),
+        modality: z.string().optional().describe('Event modality'),
+        parent_event_ids: z.array(z.string()).optional().describe('Parent event IDs (ULID or UUID)'),
+        supersedes_event_id: z.string().optional().describe('Event this supersedes'),
+        occurred_at: z.string().datetime().optional().describe('ISO 8601 timestamp'),
+        title: z.string().optional().describe('Human-readable event title'),
+        metadata: z.record(z.unknown()).optional().describe('Structured metadata JSON'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const data = await client.request('POST', '/api/v1/events', args);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_get_event', 'Get a single event by ID.', {
+        event_id: z.string().describe('Event ID (ULID or UUID)'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const data = await client.request('GET', `/api/v1/events/${args.event_id}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+}

package/dist/tools/connector_write_back.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TacitClient } from '../client.js';
+export declare function registerConnectorWriteBackTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;

package/dist/tools/connector_write_back.js

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: MIT
+// MV-1531b W3: Connector write-back MCP tool
+import { z } from 'zod';
+export function registerConnectorWriteBackTools(server, getClientFn) {
+    server.tool('tacit_connector_write_back', 'Propose structured field mutations to be written back to a connector source. Returns proposal_id, status, and mutations_count.', {
+        connector_id: z.string().min(1).describe('Connector UUID'),
+        mutations: z.array(z.object({
+            table_name: z.string().min(1),
+            record_id: z.string().min(1),
+            field_name: z.string().min(1),
+            new_value: z.unknown(),
+        })).min(1).describe('Field mutations to apply'),
+    }, async (args) => {
+        const client = await getClientFn();
+        try {
+            const result = await client.post('/api/v1/connectors/write-back', {
+                connector_id: args.connector_id,
+                mutations: args.mutations,
+            });
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}

package/dist/tools/converse.d.ts

@@ -0,0 +1,10 @@
+/**
+ * tacit_converse — conversational AI tool (MV-1523 W5)
+ *
+ * POST /api/v1/converse — SSE stream
+ * GET  /api/v1/converse/sessions — list sessions
+ * GET  /api/v1/converse/sessions/:id/messages — get messages
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TacitClient } from '../client.js';
+export declare function registerConverseTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;

package/dist/tools/converse.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+/**
+ * tacit_converse — conversational AI tool (MV-1523 W5)
+ *
+ * POST /api/v1/converse — SSE stream
+ * GET  /api/v1/converse/sessions — list sessions
+ * GET  /api/v1/converse/sessions/:id/messages — get messages
+ */
+import { z } from 'zod';
+export function registerConverseTools(server, getClientFn) {
+    server.tool('tacit_converse', 'Send a message in a conversational AI session. Returns the assistant response. Creates a new session if session_id is omitted.', {
+        message: z.string().min(1).describe('The message to send'),
+        session_id: z.string().optional().describe('Existing session UUID to continue; omit for a new session'),
+    }, async (args) => {
+        const client = await getClientFn();
+        const body = { message: args.message, channel: 'mcp' };
+        if (args.session_id)
+            body['session_id'] = args.session_id;
+        try {
+            const chunks = [];
+            let sessionId = '';
+            let structuredAnswer = null;
+            for await (const chunk of client.postSSE('/api/v1/converse', body)) {
+                try {
+                    const parsed = JSON.parse(chunk);
+                    if (parsed.type === 'session_start')
+                        sessionId = parsed.session_id;
+                    else if (parsed.type === 'token')
+                        chunks.push(parsed.delta);
+                    else if (parsed.type === 'structured_answer')
+                        structuredAnswer = parsed.data;
+                }
+                catch {
+                    chunks.push(chunk);
+                }
+            }
+            const text = chunks.join('');
+            const result = { session_id: sessionId, response: text };
+            if (structuredAnswer)
+                result['structured_answer'] = structuredAnswer;
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify(result),
+                    }],
+            };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+    server.tool('tacit_converse_sessions', 'List the user\'s conversational AI sessions.', {
+        limit: z.number().optional().describe('Max sessions to return (default 20)'),
+    }, async (args) => {
+        const client = await getClientFn();
+        try {
+            const query = {};
+            if (args.limit)
+                query['limit'] = String(args.limit);
+            const qs = new URLSearchParams(query).toString();
+            const result = await client.get(`/api/v1/converse/sessions${qs ? `?${qs}` : ''}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+    server.tool('tacit_converse_messages', 'Get messages from a conversational AI session.', {
+        session_id: z.string().describe('Session UUID'),
+        limit: z.number().optional().describe('Max messages to return (default 50)'),
+    }, async (args) => {
+        const client = await getClientFn();
+        try {
+            const query = {};
+            if (args.limit)
+                query['limit'] = String(args.limit);
+            const qs = new URLSearchParams(query).toString();
+            const result = await client.get(`/api/v1/converse/sessions/${args.session_id}/messages${qs ? `?${qs}` : ''}`);
+            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
+    });
+}

package/dist/tools/crews.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { TacitClient } from '../client.js';
+export declare function registerCrewTools(server: McpServer, getClient: () => Promise<TacitClient>): void;

package/dist/tools/crews.js

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { TacitApiError } from '../client.js';
+import { success, error } from './errors.js';
+export function registerCrewTools(server, getClient) {
+    server.tool('tacit_dispatch_crew', 'Dispatch a crew for autonomous task execution.', {
+        composition_type: z.string().describe('Crew composition type to dispatch'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const data = await client.request('POST', '/api/v1/bha/crews/dispatch', args);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_crew_status', 'Get the status and details of a crew run.', {
+        run_id: z.string().uuid().describe('Crew run UUID'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const data = await client.request('GET', `/api/v1/bha/crews/${args.run_id}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_crew_history', 'Get crew run history for the current workspace.', {}, async () => {
+        try {
+            const client = await getClient();
+            const wsId = client.workspaceId;
+            if (!wsId)
+                return error('No active workspace — call tacit_list_workspaces first');
+            const data = await client.request('GET', `/api/v1/bha/crews/history/${wsId}`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_approve_gate', 'Approve a crew gate checkpoint.', {
+        run_id: z.string().uuid().describe('Crew run UUID'),
+        gate_id: z.string().uuid().describe('Gate UUID'),
+        notes: z.string().optional().describe('Approval notes'),
+        redirect_instructions: z.string().optional().describe('Redirect instructions for the crew'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const { run_id, gate_id, ...body } = args;
+            const data = await client.request('POST', `/api/v1/bha/crews/${run_id}/gates/${gate_id}/approve`, body);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_reject_gate', 'Reject a crew gate checkpoint.', {
+        run_id: z.string().uuid().describe('Crew run UUID'),
+        gate_id: z.string().uuid().describe('Gate UUID'),
+        notes: z.string().optional().describe('Rejection notes'),
+        redirect_instructions: z.string().optional().describe('Redirect instructions for the crew'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const { run_id, gate_id, ...body } = args;
+            const data = await client.request('POST', `/api/v1/bha/crews/${run_id}/gates/${gate_id}/reject`, body);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_list_deliverables', 'List deliverables for a dossier.', {
+        dossier_id: z.string().uuid().describe('Dossier UUID'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const data = await client.request('GET', `/api/v1/bha/dossiers/${args.dossier_id}/deliverables`);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.tool('tacit_edit_deliverable', "Edit a deliverable's content.", {
+        deliverable_id: z.string().uuid().describe('Deliverable UUID'),
+        content_body: z.string().describe('New content body'),
+        edit_type: z.string().describe('Edit type identifier'),
+    }, async (args) => {
+        try {
+            const client = await getClient();
+            const { deliverable_id, ...body } = args;
+            const data = await client.request('PUT', `/api/v1/bha/deliverables/${deliverable_id}/content`, body);
+            return success(data);
+        }
+        catch (e) {
+            if (e instanceof TacitApiError)
+                return error(e.message);
+            return error(`Unexpected error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+}

package/dist/tools/drafts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Draft tools (MV-1515n W5 / FEAT-142):
+ *   tacit_draft_search — GET /api/v1/artifacts/drafts/search
+ *
+ * Drafts only (non-published) — never used by synthesis (§10 synthesis wall,
+ * ADR-182). Semantic mode sees title + first 4,000 chars. Returns 503
+ * embedding_unavailable when the embed server is down — there is no silent
+ * keyword fallback (C5).
+ *
+ * This is a separate tool from tacit_search / tacit_synthesize / tacit_recall,
+ * which are unaffected and never read draft_projections.
+ */
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { TacitClient } from '../client.js';
+export interface ToolRequest {
+    execute(): Promise<{
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+export declare const draftSearchInputSchema: z.ZodObject<{
+    q: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<["keyword", "semantic", "hybrid"]>>;
+    origin: z.ZodOptional<z.ZodEnum<["IMPORTED", "SYNTHESIZED", "WIKI_CONVERGENCE"]>>;
+    portfolio_id: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    q: string;
+    limit?: number | undefined;
+    origin?: "IMPORTED" | "SYNTHESIZED" | "WIKI_CONVERGENCE" | undefined;
+    portfolio_id?: string | undefined;
+    mode?: "hybrid" | "keyword" | "semantic" | undefined;
+}, {
+    q: string;
+    limit?: number | undefined;
+    origin?: "IMPORTED" | "SYNTHESIZED" | "WIKI_CONVERGENCE" | undefined;
+    portfolio_id?: string | undefined;
+    mode?: "hybrid" | "keyword" | "semantic" | undefined;
+}>;
+export type DraftSearchInput = z.infer<typeof draftSearchInputSchema>;
+export declare const DRAFT_SEARCH_TOOL_DEF: {
+    name: "tacit_draft_search";
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            q: {
+                type: string;
+                description: string;
+            };
+            mode: {
+                type: string;
+                enum: string[];
+                default: string;
+            };
+            origin: {
+                type: string;
+                enum: string[];
+            };
+            portfolio_id: {
+                type: string;
+            };
+            limit: {
+                type: string;
+                maximum: number;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function buildDraftSearchRequest(client: TacitClient, input: DraftSearchInput): ToolRequest;
+export declare function handleDraftSearch(args: unknown): Promise<{
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+}>;
+export declare function registerDraftTools(server: McpServer, getClientFn: () => Promise<TacitClient>): void;

package/dist/tools/drafts.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Draft tools (MV-1515n W5 / FEAT-142):
+ *   tacit_draft_search — GET /api/v1/artifacts/drafts/search
+ *
+ * Drafts only (non-published) — never used by synthesis (§10 synthesis wall,
+ * ADR-182). Semantic mode sees title + first 4,000 chars. Returns 503
+ * embedding_unavailable when the embed server is down — there is no silent
+ * keyword fallback (C5).
+ *
+ * This is a separate tool from tacit_search / tacit_synthesize / tacit_recall,
+ * which are unaffected and never read draft_projections.
+ */
+import { z } from 'zod';
+import { getClient } from '../client.js';
+import { apiErrorResult } from './errors.js';
+export const draftSearchInputSchema = z.object({
+    q: z.string().min(1).describe('Search text (required)'),
+    mode: z.enum(['keyword', 'semantic', 'hybrid']).optional().describe('Search mode (default hybrid)'),
+    origin: z.enum(['IMPORTED', 'SYNTHESIZED', 'WIKI_CONVERGENCE']).optional().describe('Filter by artifact origin'),
+    portfolio_id: z.string().optional().describe('Filter by portfolio UUID'),
+    limit: z.number().int().positive().max(50).optional().describe('Maximum results to return (max 50)'),
+});
+export const DRAFT_SEARCH_TOOL_DEF = {
+    name: 'tacit_draft_search',
+    description: 'Search DRAFT (non-published) artifacts by keyword, semantic, or hybrid mode. ' +
+        'Drafts only — this store is never read by synthesis or tacit_search/tacit_synthesize/tacit_recall (synthesis wall). ' +
+        'Semantic mode indexes title + the first 4,000 chars of body. ' +
+        'Returns HTTP 503 with error code embedding_unavailable when the embed server is down — there is no silent ' +
+        'fallback to keyword search in that case; retry with mode=keyword explicitly instead. ' +
+        'Route: GET /api/v1/artifacts/drafts/search.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            q: { type: 'string', description: 'Search text (required)' },
+            mode: { type: 'string', enum: ['keyword', 'semantic', 'hybrid'], default: 'hybrid' },
+            origin: { type: 'string', enum: ['IMPORTED', 'SYNTHESIZED', 'WIKI_CONVERGENCE'] },
+            portfolio_id: { type: 'string' },
+            limit: { type: 'number', maximum: 50 },
+        },
+        required: ['q'],
+    },
+};
+export function buildDraftSearchRequest(client, input) {
+    return {
+        async execute() {
+            const { q, mode, origin, portfolio_id, limit } = input;
+            try {
+                const params = { q };
+                if (mode)
+                    params['mode'] = mode;
+                if (origin)
+                    params['origin'] = origin;
+                if (portfolio_id)
+                    params['portfolio_id'] = portfolio_id;
+                if (limit !== undefined)
+                    params['limit'] = limit;
+                // GET /api/v1/artifacts/drafts/search
+                const result = await client.get('/api/v1/artifacts/drafts/search', params);
+                return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+            }
+            catch (err) {
+                return apiErrorResult(err, '/api/v1/artifacts/drafts/search');
+            }
+        },
+    };
+}
+export async function handleDraftSearch(args) {
+    const parsed = draftSearchInputSchema.safeParse(args);
+    if (!parsed.success) {
+        return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+    }
+    return buildDraftSearchRequest(getClient(), parsed.data).execute();
+}
+export function registerDraftTools(server, getClientFn) {
+    server.tool('tacit_draft_search', 'Search DRAFT (non-published) artifacts by keyword, semantic, or hybrid mode. Returns HTTP 503 when embed server is down.', {
+        q: z.string().min(1).describe('Search text (required)'),
+        mode: z.enum(['keyword', 'semantic', 'hybrid']).optional().describe('Search mode (default hybrid)'),
+        origin: z.enum(['IMPORTED', 'SYNTHESIZED', 'WIKI_CONVERGENCE']).optional().describe('Filter by artifact origin'),
+        portfolio_id: z.string().optional().describe('Filter by portfolio UUID'),
+        limit: z.number().int().positive().max(50).optional().describe('Maximum results to return (max 50)'),
+    }, async (args) => {
+        const client = await getClientFn();
+        return buildDraftSearchRequest(client, args).execute();
+    });
+}

package/dist/tools/errors.d.ts

@@ -0,0 +1,15 @@
+type ToolResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export declare function success(data: unknown): ToolResult;
+export declare function error(message: string): ToolResult & {
+    isError: true;
+};
+export declare function apiErrorResult(err: unknown, endpoint: string): ToolResult & {
+    isError: boolean;
+};
+export {};

package/dist/tools/errors.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+import { TacitApiError, TokenExpiredError } from '../client.js';
+export function success(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function error(message) {
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}
+export function apiErrorResult(err, endpoint) {
+    if (err instanceof TokenExpiredError) {
+        return {
+            content: [{ type: 'text', text: err.message }],
+            isError: true,
+        };
+    }
+    if (err instanceof TacitApiError) {
+        return { content: [{ type: 'text', text: `API error ${err.statusCode} on ${endpoint}: ${err.body}` }], isError: true };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}