@cyanheads/cyanheads-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/describe.tool.js

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview cyanheads_describe — return connection URL and per-client install snippets
+ * for a named tool or server.
+ * Uses z.discriminatedUnion on 'kind' so the linter walks each branch independently
+ * and format() can dispatch cleanly.
+ * @module mcp-server/tools/definitions/describe
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCatalogService } from '../../../services/catalog/catalog-service.js';
+import { buildAllSnippets } from '../../../services/catalog/snippets.js';
+export const describeTool = tool('cyanheads_describe', {
+    title: 'Describe Fleet Tool or Server',
+    description: 'Return the description, connection URL, and per-client install snippets for a named tool or ' +
+        'server. For tools: the description and the server it belongs to. ' +
+        'For servers: connection URL and install snippets for every supported client (or one specific ' +
+        'client when the client parameter is specified). Call cyanheads_search first to find valid names.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    auth: ['tool:cyanheads_describe:read'],
+    input: z.object({
+        name: z
+            .string()
+            .min(1)
+            .describe('Tool name (snake_case, e.g. "earthquake_search") or server name ' +
+            '(kebab-case, e.g. "earthquake-mcp-server"). Use cyanheads_search to discover valid names.'),
+        kind: z
+            .enum(['tool', 'server'])
+            .optional()
+            .describe('Whether name refers to a tool or server. Omit to auto-detect: names containing ' +
+            'underscores are treated as tools; names containing hyphens are treated as servers.'),
+        client: z
+            .enum(['claude-desktop', 'claude-code', 'cursor', 'cline'])
+            .optional()
+            .describe('Return the install snippet for this specific client only. ' +
+            'Omit to return snippets for all supported clients.'),
+    }),
+    output: z.object({
+        result: z
+            .discriminatedUnion('kind', [
+            z.object({
+                kind: z.literal('tool').describe('Resolved as a tool entry.'),
+                name: z.string().describe('Resolved name (as looked up).'),
+                description: z.string().describe('Brief description of what the tool does.'),
+                server: z.string().describe('Server package name that owns this tool.'),
+            }),
+            z.object({
+                kind: z.literal('server').describe('Resolved as a server entry.'),
+                name: z.string().describe('Resolved name (as looked up).'),
+                displayName: z.string().describe('Human-readable server label.'),
+                description: z.string().describe('Brief description of what the server does.'),
+                version: z.string().describe('Published version captured at fleet-generation time.'),
+                npm: z.string().describe('npm package name (e.g. "@cyanheads/arxiv-mcp-server").'),
+                github: z.string().describe('GitHub repository URL.'),
+                endpoint: z.string().describe('HTTP SSE endpoint for the hosted deployment.'),
+                auth: z
+                    .string()
+                    .describe('Auth requirement for the hosted deployment (currently always "none").'),
+                toolCount: z.number().describe('Number of tools exposed by this server.'),
+                installSnippets: z
+                    .array(z
+                    .object({
+                    client: z
+                        .enum(['claude-desktop', 'claude-code', 'cursor', 'cline'])
+                        .describe('MCP client this snippet targets.'),
+                    label: z.string().describe('Human-readable install method label.'),
+                    payload: z.string().describe('Install payload (JSON fragment or CLI command).'),
+                })
+                    .describe('A single install instruction entry.'))
+                    .describe('Install instructions, one per supported client (or filtered by input.client).'),
+            }),
+        ])
+            .describe('The resolved entry — either a tool detail or a server detail depending on the resolved kind.'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No tool or server with the given name exists in the catalog.',
+            recovery: 'Use cyanheads_search to find the correct name, then call cyanheads_describe again.',
+        },
+        {
+            reason: 'ambiguous_kind',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Name matches both a tool and a server (collision in catalog).',
+            recovery: 'Set the kind parameter to "tool" or "server" to disambiguate.',
+        },
+        {
+            reason: 'catalog_empty',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Catalog has not finished loading.',
+            recovery: 'Retry in a few seconds; the catalog is still loading.',
+            retryable: true,
+        },
+    ],
+    // biome-ignore lint/suspicious/useAwait: handler has no I/O but must return a Promise for the framework
+    async handler(input, ctx) {
+        ctx.log.info('Describing catalog entry', { name: input.name, kind: input.kind });
+        const catalog = getCatalogService();
+        // Resolve kind: explicit > auto-detect from name format.
+        let resolvedKind = input.kind;
+        if (!resolvedKind) {
+            // Fleet invariant: tool names use underscores, server names use hyphens.
+            if (input.name.includes('_')) {
+                resolvedKind = 'tool';
+            }
+            else if (input.name.includes('-')) {
+                resolvedKind = 'server';
+            }
+        }
+        const toolEntry = resolvedKind !== 'server' ? catalog.getTool(input.name) : null;
+        const serverEntry = resolvedKind !== 'tool' ? catalog.getServer(input.name) : null;
+        // Ambiguity check (can happen if resolvedKind is undefined and name has neither _ nor -).
+        if (toolEntry && serverEntry) {
+            throw ctx.fail('ambiguous_kind', `"${input.name}" matches both a tool and a server`, {
+                ...ctx.recoveryFor('ambiguous_kind'),
+                name: input.name,
+            });
+        }
+        if (toolEntry) {
+            return {
+                result: {
+                    kind: 'tool',
+                    name: input.name,
+                    description: toolEntry.description,
+                    server: toolEntry.serverRecord.name,
+                },
+            };
+        }
+        if (serverEntry) {
+            const allSnippets = buildAllSnippets(serverEntry);
+            const snippets = input.client
+                ? allSnippets.filter((s) => s.client === input.client)
+                : allSnippets;
+            return {
+                result: {
+                    kind: 'server',
+                    name: input.name,
+                    displayName: serverEntry.displayName,
+                    description: serverEntry.description,
+                    version: serverEntry.version,
+                    npm: serverEntry.npm,
+                    github: serverEntry.github,
+                    endpoint: serverEntry.endpoint,
+                    auth: serverEntry.auth,
+                    toolCount: serverEntry.tools.length,
+                    installSnippets: snippets,
+                },
+            };
+        }
+        throw ctx.fail('not_found', `No tool or server named "${input.name}" in the catalog`, {
+            ...ctx.recoveryFor('not_found'),
+            name: input.name,
+        });
+    },
+    format: ({ result }) => {
+        const lines = [];
+        if (result.kind === 'tool') {
+            lines.push(`# Tool: ${result.name}`);
+            lines.push(`**Server:** ${result.server}`);
+            lines.push('');
+            lines.push(`**Kind:** tool`);
+            lines.push('');
+            lines.push(`## Description`);
+            lines.push(result.description);
+        }
+        else {
+            lines.push(`# Server: ${result.name}`);
+            lines.push(`**Kind:** server`);
+            lines.push(`**Display name:** ${result.displayName}`);
+            lines.push(`**Version:** ${result.version}`);
+            lines.push(`**npm:** ${result.npm}`);
+            lines.push(`**GitHub:** ${result.github}`);
+            lines.push(`**Auth:** ${result.auth}`);
+            lines.push(`**Tool count:** ${result.toolCount}`);
+            lines.push(`**Endpoint:** ${result.endpoint}`);
+            lines.push('');
+            lines.push('## Description');
+            lines.push(result.description);
+            lines.push('');
+            lines.push('## Install Snippets');
+            for (const snippet of result.installSnippets) {
+                lines.push(`### ${snippet.label} (${snippet.client})`);
+                lines.push('```');
+                lines.push(snippet.payload);
+                lines.push('```');
+                lines.push('');
+            }
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=describe.tool.js.map

package/dist/mcp-server/tools/definitions/describe.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/describe.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/search.tool.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview cyanheads_search — semantic search across fleet tools and servers.
+ * Embeds the query at runtime and dot-products against in-memory L2-normalized
+ * document vectors loaded from fleet.json.
+ * @module mcp-server/tools/definitions/search
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const searchTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<{
+        tools: "tools";
+        servers: "servers";
+    }>>;
+    category: z.ZodOptional<z.ZodEnum<{
+        research: "research";
+        government: "government";
+        "public-data": "public-data";
+        utility: "utility";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        server: z.ZodString;
+        brief: z.ZodString;
+        category: z.ZodEnum<{
+            research: "research";
+            government: "government";
+            "public-data": "public-data";
+            utility: "utility";
+        }>;
+        score: z.ZodNumber;
+    }, z.core.$strip>>;
+    totalMatched: z.ZodNumber;
+    query: z.ZodString;
+    scope: z.ZodEnum<{
+        tools: "tools";
+        servers: "servers";
+    }>;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_results";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "Query produced no relevant matches.";
+    readonly recovery: "Broaden the query, remove the category filter, or try scope \"servers\" to find the right server first.";
+}, {
+    readonly reason: "catalog_empty";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Catalog has not finished loading.";
+    readonly recovery: "Retry in a few seconds; the catalog is still loading.";
+    readonly retryable: true;
+}]>;
+//# sourceMappingURL=search.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search.tool.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0IrB,CAAC"}

package/dist/mcp-server/tools/definitions/search.tool.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview cyanheads_search — semantic search across fleet tools and servers.
+ * Embeds the query at runtime and dot-products against in-memory L2-normalized
+ * document vectors loaded from fleet.json.
+ * @module mcp-server/tools/definitions/search
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getCatalogService } from '../../../services/catalog/catalog-service.js';
+export const searchTool = tool('cyanheads_search', {
+    title: 'Search Fleet Tools and Servers',
+    description: 'Search fleet tools and servers by natural-language description. Returns ranked matches with ' +
+        'brief summaries and the server each tool belongs to. Use scope "servers" to find which ' +
+        'server handles a workflow; use the default scope "tools" to find specific tools. ' +
+        'Call cyanheads_describe on a result name to get install snippets and the connection URL.',
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    auth: ['tool:cyanheads_search:read'],
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Natural language search query. Describe what you want to accomplish, a workflow, or a capability area.'),
+        scope: z
+            .enum(['tools', 'servers'])
+            .default('tools')
+            .describe('What to search. "tools" returns individual tool matches; "servers" returns server-level matches.'),
+        category: z
+            .enum(['research', 'government', 'public-data', 'utility'])
+            .optional()
+            .describe('Filter by catalog category. Omit to search all categories.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .default(5)
+            .describe('Maximum number of results to return (1-20). Default 5.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z
+            .object({
+            name: z
+                .string()
+                .describe('Tool name (snake_case) or server name (kebab-case) depending on scope.'),
+            server: z
+                .string()
+                .describe('Server package name that owns this tool (e.g. "arxiv-mcp-server"). Same as name when scope is "servers".'),
+            brief: z.string().describe('One-line summary of what this tool or server does.'),
+            category: z
+                .enum(['research', 'government', 'public-data', 'utility'])
+                .describe('Catalog category for the owning server.'),
+            score: z
+                .number()
+                .describe('Cosine similarity between query and entry, in [0, 1]. Higher is better. Compare only within a single response.'),
+        })
+            .describe('A single search result entry.'))
+            .describe('Ranked matches, best first.'),
+        totalMatched: z.number().describe('Total relevant matches before the limit was applied.'),
+        query: z.string().describe('The query that was searched.'),
+        scope: z.enum(['tools', 'servers']).describe('Scope that was searched.'),
+    }),
+    errors: [
+        {
+            reason: 'no_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'Query produced no relevant matches.',
+            recovery: 'Broaden the query, remove the category filter, or try scope "servers" to find the right server first.',
+        },
+        {
+            reason: 'catalog_empty',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Catalog has not finished loading.',
+            recovery: 'Retry in a few seconds; the catalog is still loading.',
+            retryable: true,
+        },
+    ],
+    async handler(input, ctx) {
+        ctx.log.info('Searching catalog', {
+            query: input.query,
+            scope: input.scope,
+            limit: input.limit,
+        });
+        const catalog = getCatalogService();
+        const allResults = await catalog.search({
+            query: input.query,
+            scope: input.scope,
+            ...(input.category ? { category: input.category } : {}),
+        });
+        const totalMatched = allResults.length;
+        if (totalMatched === 0) {
+            throw ctx.fail('no_results', `No ${input.scope} matched "${input.query}"`, {
+                ...ctx.recoveryFor('no_results'),
+                query: input.query,
+                scope: input.scope,
+                category: input.category,
+            });
+        }
+        const results = allResults.slice(0, input.limit);
+        ctx.log.info('Search complete', { totalMatched, returned: results.length });
+        return {
+            results,
+            totalMatched,
+            query: input.query,
+            scope: input.scope,
+        };
+    },
+    format: (result) => {
+        const lines = [
+            `**Query:** ${result.query}  **Scope:** ${result.scope}`,
+            `**Matched:** ${result.totalMatched} total, showing ${result.results.length}`,
+            '',
+        ];
+        for (const item of result.results) {
+            lines.push(`### ${item.name}`);
+            lines.push(`**Server:** ${item.server}  |  **Category:** ${item.category}  |  **Score:** ${item.score.toFixed(3)}`);
+            lines.push(item.brief);
+            lines.push('');
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=search.tool.js.map

package/dist/mcp-server/tools/definitions/search.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/search.tool.ts"],"names":[],"mappings":"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"}

package/dist/services/catalog/catalog-service.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview CatalogService — fleet catalog with semantic search.
+ * Loads fleet.json (v2 with baked embeddings) at startup, packs vectors into a
+ * Float32Array for cache locality, and serves cosine-similarity search by
+ * embedding the query at runtime and dot-producting against the in-memory index.
+ * Polls the remote payload on a configurable interval; atomic swap on change.
+ * @module services/catalog/catalog-service
+ */
+import type { ServerConfig } from '../../config/server-config.js';
+import { type IEmbeddingsRuntime } from './embeddings-runtime.js';
+import type { CatalogCategory, CatalogRecord, CatalogSearchResult, CatalogTool, ICatalogService } from './types.js';
+type CatalogServiceConfig = Pick<ServerConfig, 'catalogUrl' | 'catalogFetchTimeoutMs' | 'catalogRefreshSeconds' | 'embeddingModelId' | 'similarityFloor'>;
+export declare class CatalogService implements ICatalogService {
+    private _index;
+    private readonly _provider;
+    private readonly _embeddings;
+    private readonly _config;
+    private _refreshTimer;
+    constructor(config: CatalogServiceConfig, embeddings?: IEmbeddingsRuntime);
+    initialize(): Promise<void>;
+    search(params: {
+        query: string;
+        scope: 'tools' | 'servers';
+        category?: CatalogCategory;
+        limit?: number;
+    }): Promise<CatalogSearchResult[]>;
+    getTool(name: string): (CatalogTool & {
+        serverRecord: CatalogRecord;
+    }) | null;
+    getServer(name: string): CatalogRecord | null;
+    listCategories(): CatalogCategory[];
+    stats(): {
+        toolCount: number;
+        serverCount: number;
+        initializedAt: string;
+        embeddingModel: string;
+    };
+    /** Stop the background refresh timer (test-only / shutdown). */
+    shutdown(): void;
+    private _assertModelMatch;
+    private _buildIndex;
+    private _maybeRefresh;
+    private _assertInitialized;
+}
+export declare function initCatalogService(config: CatalogServiceConfig, embeddings?: IEmbeddingsRuntime): void;
+export declare function getCatalogService(): CatalogService;
+/** Test-only reset. */
+export declare function resetCatalogServiceForTests(): void;
+export {};
+//# sourceMappingURL=catalog-service.d.ts.map

package/dist/services/catalog/catalog-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/catalog-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,KAAK,kBAAkB,EAAiC,MAAM,yBAAyB,CAAC;AAEjG,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,WAAW,EAEX,eAAe,EAChB,MAAM,YAAY,CAAC;AAoBpB,KAAK,oBAAoB,GAAG,IAAI,CAC9B,YAAY,EACV,YAAY,GACZ,uBAAuB,GACvB,uBAAuB,GACvB,kBAAkB,GAClB,iBAAiB,CACpB,CAAC;AAMF,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,aAAa,CAA+C;gBAExD,MAAM,EAAE,oBAAoB,EAAE,UAAU,CAAC,EAAE,kBAAkB;IAMnE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB3B,MAAM,CAAC,MAAM,EAAE;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;QAC3B,QAAQ,CAAC,EAAE,eAAe,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAkDlC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG;QAAE,YAAY,EAAE,aAAa,CAAA;KAAE,CAAC,GAAG,IAAI;IAK7E,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;IAK7C,cAAc,IAAI,eAAe,EAAE;IAOnC,KAAK,IAAI;QACP,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KACxB;IAUD,gEAAgE;IAChE,QAAQ,IAAI,IAAI;IAWhB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,WAAW;YAwDL,aAAa;IA2B3B,OAAO,CAAC,kBAAkB;CAQ3B;AAsBD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,oBAAoB,EAC5B,UAAU,CAAC,EAAE,kBAAkB,GAC9B,IAAI,CAEN;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAQlD;AAED,uBAAuB;AACvB,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}