@cyanheads/cyanheads-mcp-server 0.1.1

package/dist/services/catalog/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Shared types for the catalog service — CatalogRecord, CatalogTool,
+ * FleetPayload (v2 with baked embeddings), InstallSnippet, ClientId,
+ * and the service interface.
+ * @module services/catalog/types
+ */
+/** Supported MCP client identifiers for install snippets. */
+export type ClientId = 'claude-desktop' | 'claude-code' | 'cursor' | 'cline';
+/** Catalog category for a fleet server. */
+export type CatalogCategory = 'research' | 'government' | 'public-data' | 'utility';
+/** Single tool entry inside a CatalogRecord. */
+export interface CatalogTool {
+    /** Human-readable description. */
+    description: string;
+    /**
+     * L2-normalized, Matryoshka-truncated embedding vector.
+     * Length matches FleetPayload.embeddingDims.
+     */
+    embedding: number[];
+    /** Fully-qualified name: snake_case (e.g. "earthquake_search"). */
+    name: string;
+}
+/** Per-client install snippet. */
+export interface InstallSnippet {
+    /** MCP client identifier. */
+    client: ClientId;
+    /** Human-readable label for the install method. */
+    label: string;
+    /**
+     * The install payload. Shape varies by client:
+     * - claude-desktop: JSON fragment for mcpServers block
+     * - claude-code: CLI command string
+     * - cursor: JSON fragment for .cursor/mcp.json mcpServers block
+     * - cline: JSON fragment for Cline's MCP settings
+     */
+    payload: string;
+}
+/** One fleet server record, mirroring the fleet.json servers[] entry. */
+export interface CatalogRecord {
+    /**
+     * Auth requirement for the hosted deployment.
+     * Open string for forward-compatibility — currently always "none".
+     */
+    auth: string;
+    /** Thematic grouping for filter facets. */
+    category: CatalogCategory;
+    /** One-line description of what this server does. */
+    description: string;
+    /** Human label (e.g. "arXiv"). */
+    displayName: string;
+    /**
+     * L2-normalized, Matryoshka-truncated embedding vector of
+     * `${displayName}\n${description}`. Length matches FleetPayload.embeddingDims.
+     */
+    embedding: number[];
+    /** HTTP SSE endpoint — always present; the catalog covers hosted servers only. */
+    endpoint: string;
+    /** GitHub repository URL. */
+    github: string;
+    /** Package name without scope (e.g. "arxiv-mcp-server"). */
+    name: string;
+    /** npm package name (scoped, e.g. "@cyanheads/arxiv-mcp-server"). */
+    npm: string;
+    /** Tool entries for this server, each with its own embedding. */
+    tools: CatalogTool[];
+    /** Published version captured at fleet-generation time (e.g. "1.2.7"). */
+    version: string;
+}
+/** Top-level payload returned from the remote fleet.json URL. */
+export interface FleetPayload {
+    /** Dimensionality of every embedding in the payload. */
+    embeddingDims: number;
+    /** Hugging Face model id used to produce the embeddings. */
+    embeddingModel: string;
+    /**
+     * Prefix that must be prepended to query text before embedding at runtime.
+     * Documents are embedded without this prefix; only queries get it.
+     */
+    embeddingQueryPrefix: string;
+    /** ISO 8601 UTC timestamp when the payload was generated. */
+    generatedAt: string;
+    /** Fleet server records. */
+    servers: CatalogRecord[];
+    /** Schema version. Currently "2". */
+    version: '2';
+}
+/** Result row returned from catalog searches. */
+export interface CatalogSearchResult {
+    /** Brief description for display. */
+    brief: string;
+    /** Catalog category for the owning server. */
+    category: CatalogCategory;
+    /** Tool or server name, depending on scope. */
+    name: string;
+    /** Cosine similarity in [0, 1]. Higher is better. */
+    score: number;
+    /** Server that owns this result. */
+    server: string;
+}
+/** Service interface. */
+export interface ICatalogService {
+    /** Look up a server by exact name. Returns null if not found. */
+    getServer(name: string): CatalogRecord | null;
+    /** Look up a tool by exact name. Returns null if not found. */
+    getTool(name: string): (CatalogTool & {
+        serverRecord: CatalogRecord;
+    }) | null;
+    /**
+     * Fetch fleet.json, validate, build the vector index, and load the embedding model.
+     * Starts the background refresh timer if configured.
+     */
+    initialize(): Promise<void>;
+    /** List all category strings present in the catalog. */
+    listCategories(): CatalogCategory[];
+    /**
+     * Semantic search. Embeds the query, computes cosine similarity against
+     * every catalog entry within the requested scope, filters by category and
+     * by the configured similarity floor, sorts descending, and returns the
+     * top `limit` (or every match when `limit` is omitted).
+     */
+    search(params: {
+        query: string;
+        scope: 'tools' | 'servers';
+        category?: CatalogCategory;
+        limit?: number;
+    }): Promise<CatalogSearchResult[]>;
+    /** Catalog summary for diagnostics. */
+    stats(): {
+        toolCount: number;
+        serverCount: number;
+        initializedAt: string;
+        embeddingModel: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/catalog/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/catalog/types.ts"],"names":[],"mappings":"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"}

package/dist/services/catalog/types.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Shared types for the catalog service — CatalogRecord, CatalogTool,
+ * FleetPayload (v2 with baked embeddings), InstallSnippet, ClientId,
+ * and the service interface.
+ * @module services/catalog/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/catalog/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@cyanheads/cyanheads-mcp-server",
+  "mcpName": "io.github.cyanheads/cyanheads-mcp-server",
+  "version": "0.1.1",
+  "description": "Fleet discovery server for the cyanheads MCP ecosystem — semantic search for tools and install snippets.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cyanheads-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "changelog/",
+    "dist/",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md",
+    "AGENTS.md",
+    "Dockerfile",
+    "server.json"
+  ],
+  "author": "cyanheads <casey@caseyjhand.com> (https://github.com/cyanheads/cyanheads-mcp-server#readme)",
+  "homepage": "https://github.com/cyanheads/cyanheads-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/cyanheads/cyanheads-mcp-server/issues"
+  },
+  "scripts": {
+    "build": "tsx scripts/build.ts",
+    "rebuild": "tsx scripts/clean.ts && tsx scripts/build.ts",
+    "clean": "tsx scripts/clean.ts",
+    "devcheck": "tsx scripts/devcheck.ts",
+    "audit:refresh": "rm -f bun.lock && bun install && bun audit",
+    "tree": "tsx scripts/tree.ts",
+    "list-skills": "tsx scripts/list-skills.ts",
+    "format": "biome check --write --unsafe .",
+    "lint:mcp": "tsx scripts/lint-mcp.ts",
+    "changelog:build": "tsx scripts/build-changelog.ts",
+    "changelog:check": "tsx scripts/build-changelog.ts --check",
+    "test": "vitest run",
+    "start": "node dist/index.js",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "mcp-discovery",
+    "mcp-fleet",
+    "semantic-search",
+    "cyanheads",
+    "typescript",
+    "bun"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/cyanheads-mcp-server.git"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.9.11",
+    "@huggingface/transformers": "4.2.0",
+    "pino-pretty": "^13.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@types/node": "^25.6.0",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}

package/server.json

@@ -0,0 +1,141 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.cyanheads/cyanheads-mcp-server",
+  "description": "Fleet discovery server for the cyanheads MCP ecosystem — semantic search for tools and install snippets.",
+  "repository": {
+    "url": "https://github.com/cyanheads/cyanheads-mcp-server",
+    "source": "github"
+  },
+  "version": "0.1.1",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/cyanheads-mcp-server",
+      "runtimeHint": "node",
+      "version": "0.1.1",
+      "packageArguments": [
+        { "type": "positional", "value": "run" },
+        { "type": "positional", "value": "start:stdio" }
+      ],
+      "environmentVariables": [
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Minimum log level: debug, info, notice, warning, error.",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        },
+        {
+          "name": "CATALOG_URL",
+          "description": "Remote fleet.json endpoint (schema v2 with baked embeddings).",
+          "format": "string",
+          "isRequired": false,
+          "default": "https://caseyjhand.com/fleet.json"
+        },
+        {
+          "name": "CATALOG_REFRESH_SECONDS",
+          "description": "Background poll interval for fleet.json refresh. 0 disables.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3600"
+        },
+        {
+          "name": "EMBEDDING_MODEL_ID",
+          "description": "Hugging Face model id for query embedding. Must match fleet.json.embeddingModel.",
+          "format": "string",
+          "isRequired": false,
+          "default": "Snowflake/snowflake-arctic-embed-m-v1.5"
+        },
+        {
+          "name": "SIMILARITY_FLOOR",
+          "description": "Cosine similarity cutoff for cyanheads_search results (0-1).",
+          "format": "string",
+          "isRequired": false,
+          "default": "0.3"
+        }
+      ],
+      "transport": { "type": "stdio" }
+    },
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@cyanheads/cyanheads-mcp-server",
+      "runtimeHint": "node",
+      "version": "0.1.1",
+      "packageArguments": [
+        { "type": "positional", "value": "run" },
+        { "type": "positional", "value": "start:http" }
+      ],
+      "environmentVariables": [
+        {
+          "name": "MCP_HTTP_HOST",
+          "description": "Hostname for the HTTP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "127.0.0.1"
+        },
+        {
+          "name": "MCP_HTTP_PORT",
+          "description": "Port to run the HTTP server on.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3010"
+        },
+        {
+          "name": "MCP_HTTP_ENDPOINT_PATH",
+          "description": "Endpoint path for the MCP server.",
+          "format": "string",
+          "isRequired": false,
+          "default": "/mcp"
+        },
+        {
+          "name": "MCP_AUTH_MODE",
+          "description": "Authentication mode: none, jwt, or oauth.",
+          "format": "string",
+          "isRequired": false,
+          "default": "none"
+        },
+        {
+          "name": "MCP_LOG_LEVEL",
+          "description": "Minimum log level: debug, info, notice, warning, error.",
+          "format": "string",
+          "isRequired": false,
+          "default": "info"
+        },
+        {
+          "name": "CATALOG_URL",
+          "description": "Remote fleet.json endpoint (schema v2 with baked embeddings).",
+          "format": "string",
+          "isRequired": false,
+          "default": "https://caseyjhand.com/fleet.json"
+        },
+        {
+          "name": "CATALOG_REFRESH_SECONDS",
+          "description": "Background poll interval for fleet.json refresh. 0 disables.",
+          "format": "string",
+          "isRequired": false,
+          "default": "3600"
+        },
+        {
+          "name": "EMBEDDING_MODEL_ID",
+          "description": "Hugging Face model id for query embedding. Must match fleet.json.embeddingModel.",
+          "format": "string",
+          "isRequired": false,
+          "default": "Snowflake/snowflake-arctic-embed-m-v1.5"
+        },
+        {
+          "name": "SIMILARITY_FLOOR",
+          "description": "Cosine similarity cutoff for cyanheads_search results (0-1).",
+          "format": "string",
+          "isRequired": false,
+          "default": "0.3"
+        }
+      ],
+      "transport": {
+        "type": "streamable-http",
+        "url": "http://localhost:3010/mcp"
+      }
+    }
+  ]
+}