@totemsdk/mcp-server 0.1.0 → 0.3.0

package/dist/tools.js

@@ -1,6 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOOL_DEFINITIONS = void 0;
 exports.handleToolCall = handleToolCall;
+const template_catalog_js_1 = require("./template-catalog.js");
+const indexer_js_1 = require("./indexer.js");
+const index_store_js_1 = require("./index-store.js");
+/**
+ * The single source of truth for the MCP tool catalog. `index.ts` advertises
+ * these and `handleToolCall` dispatches them; the `mcp.test.ts` drift guard
+ * asserts the two never diverge.
+ */
+exports.TOOL_DEFINITIONS = [
+    { name: 'search-symbol', description: 'Search for a symbol (function, type, class) across all packages', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Partial symbol name to search' } }, required: ['query'] } },
+    { name: 'find-type', description: 'Find type definitions (interfaces, classes, type aliases) matching a pattern', inputSchema: { type: 'object', properties: { pattern: { type: 'string', description: 'Type name pattern to search' } }, required: ['pattern'] } },
+    { name: 'dependency-graph', description: 'Get dependency graph for a package — inbound dependents or outbound dependencies', inputSchema: { type: 'object', properties: { package: { type: 'string', description: 'Package name (e.g. @totemsdk/edge-opcua)' }, direction: { type: 'string', enum: ['in', 'out', 'all'], description: 'Dependency direction' } }, required: ['package'] } },
+    { name: 'validate-import', description: 'Check whether a cross-package import is valid', inputSchema: { type: 'object', properties: { from: { type: 'string', description: 'Source package name' }, to: { type: 'string', description: 'Target package name' }, symbol: { type: 'string', description: 'Optional: specific symbol to check' } }, required: ['from', 'to'] } },
+    { name: 'scaffold-adapter', description: 'Generate boilerplate for a new edge protocol adapter', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Package name suffix' }, protocol: { type: 'string', description: 'Protocol name (PascalCase)' }, commands: { type: 'array', items: { type: 'string' }, description: 'Transport port methods' } }, required: ['name', 'protocol'] } },
+    { name: 'scaffold-package', description: 'Generate boilerplate for a new @totemsdk package', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Package name (without @totemsdk/ prefix)' }, deps: { type: 'array', items: { type: 'string' }, description: 'Dependency package names' } }, required: ['name'] } },
+    { name: 'package-stats', description: 'Get statistics about a package — export counts, Rust/Go, tests, deps', inputSchema: { type: 'object', properties: { name: { type: 'string', description: 'Package name' } }, required: ['name'] } },
+    { name: 'list-exports', description: 'List exports of a package', inputSchema: { type: 'object', properties: { package: { type: 'string', description: 'Package name' }, kind: { type: 'string', enum: ['function', 'type', 'interface', 'class', 'const', ''], description: 'Filter by export kind' }, filter: { type: 'string', description: 'Filter by name substring' } }, required: ['package'] } },
+    { name: 'suggest-template', description: 'Suggest KISSVM script templates matching a use case — describes what you want to do and returns matching templates with import paths', inputSchema: { type: 'object', properties: { usecase: { type: 'string', description: 'Describe what you want to do (e.g. "time-lock funds until a block height", "vote tally with quorum", "identity verification")' } }, required: ['usecase'] } },
+    { name: 'read-source', description: "Read a source file from a package's src/ directory (e.g. package '@totemsdk/core', path 'treekey.ts')", inputSchema: { type: 'object', properties: { package: { type: 'string', description: 'Package name (e.g. @totemsdk/core)' }, path: { type: 'string', description: 'Path relative to the package src/ directory' } }, required: ['package', 'path'] } },
+    { name: 'list-packages', description: 'List SDK packages, optionally filtered by domain or name substring', inputSchema: { type: 'object', properties: { domain: { type: 'string', description: 'Optional domain filter (e.g. edge/runtime... see totemsdk://domain-map)' }, filter: { type: 'string', description: 'Optional package-name substring filter' } } } },
+    { name: 'search-packages', description: 'Search packages by keyword across name, description, keywords and exports (e.g. "wots lease coordination")', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Free-text query' }, domain: { type: 'string', description: 'Optional domain filter' }, limit: { type: 'number', description: 'Max results (default 15)' } }, required: ['query'] } },
+    { name: 'refresh-index', description: 'Rebuild the SDK index from the filesystem (development convenience) and report counts', inputSchema: { type: 'object', properties: {} } },
+];
 function handleToolCall(name, args, index) {
     switch (name) {
         case 'search-symbol': return searchSymbol(args, index);
@@ -11,9 +35,94 @@ function handleToolCall(name, args, index) {
         case 'scaffold-package': return scaffoldPackage(args);
         case 'package-stats': return packageStats(args, index);
         case 'list-exports': return listExports(args, index);
+        case 'suggest-template': return suggestTemplate(args);
+        case 'read-source': return readSource(args);
+        case 'list-packages': return listPackages(args, index);
+        case 'search-packages': return searchPackages(args, index);
+        case 'refresh-index': return refreshIndexTool();
         default: return { content: [{ type: 'text', text: `Unknown tool: ${name}` }], isError: true };
     }
 }
+function refreshIndexTool() {
+    const idx = (0, index_store_js_1.refreshIndex)();
+    return {
+        content: [{
+                type: 'text',
+                text: `Index rebuilt: ${Object.keys(idx.packages).length} packages, ${Object.keys(idx.symbolIndex).length} symbols, ${Object.keys(idx.domainMap).length} domains.`,
+            }],
+    };
+}
+function searchPackages(args, index) {
+    const query = String(args.query || '').toLowerCase().trim();
+    if (!query)
+        return { content: [{ type: 'text', text: 'query is required' }], isError: true };
+    const domain = args.domain;
+    const limit = Number.isFinite(args.limit) ? Number(args.limit) : 15;
+    const terms = query.split(/\s+/).filter(Boolean);
+    const scored = Object.values(index.packages)
+        .filter(p => !domain || p.domain === domain)
+        .map(p => {
+        const haystackName = p.name.toLowerCase();
+        const haystackDesc = p.description.toLowerCase();
+        const haystackKw = (p.keywords ?? []).join(' ').toLowerCase();
+        const haystackExports = [
+            ...p.exports.functions, ...p.exports.types, ...p.exports.classes, ...p.exports.interfaces, ...p.exports.consts,
+        ].join(' ').toLowerCase();
+        let score = 0;
+        for (const t of terms) {
+            if (haystackName.includes(t))
+                score += 4;
+            if (haystackKw.includes(t))
+                score += 3;
+            if (haystackExports.includes(t))
+                score += 2;
+            if (haystackDesc.includes(t))
+                score += 1;
+        }
+        return { p, score };
+    })
+        .filter(r => r.score > 0)
+        .sort((a, b) => b.score - a.score || a.p.name.localeCompare(b.p.name))
+        .slice(0, limit);
+    if (scored.length === 0) {
+        return { content: [{ type: 'text', text: `No packages matched '${query}'` }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `Found ${scored.length} package(s) for '${query}':\n\n` +
+                    scored.map(r => `  ${r.p.name}@${r.p.version} [${r.p.domain}] (score ${r.score}) — ${r.p.description}`).join('\n'),
+            }],
+    };
+}
+function readSource(args) {
+    const pkg = args.package;
+    const file = args.path;
+    if (!pkg || !file)
+        return { content: [{ type: 'text', text: 'package and path are required' }], isError: true };
+    const content = (0, indexer_js_1.readSourceFile)(pkg, file);
+    if (content === null) {
+        return { content: [{ type: 'text', text: `Source not found: ${pkg}/src/${file}` }], isError: true };
+    }
+    return { content: [{ type: 'text', text: content }] };
+}
+function listPackages(args, index) {
+    const domain = args.domain;
+    const filter = args.filter?.toLowerCase();
+    const rows = Object.values(index.packages)
+        .filter(p => (!domain || p.domain === domain) && (!filter || p.name.toLowerCase().includes(filter)))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (rows.length === 0) {
+        return { content: [{ type: 'text', text: 'No packages matched' }] };
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: `${rows.length} package(s):\n\n` +
+                    rows.map(p => `  ${p.name}@${p.version} [${p.domain}] — ${p.description}`).join('\n'),
+            }],
+    };
+}
 function searchSymbol(args, index) {
     const query = (args.query || '').toLowerCase();
     if (!query)
@@ -22,7 +131,13 @@ function searchSymbol(args, index) {
     for (const [symbol, entries] of Object.entries(index.symbolIndex)) {
         if (symbol.toLowerCase().includes(query)) {
             for (const entry of entries) {
-                results.push({ symbol, package: entry.package, kind: entry.kind });
+                results.push({
+                    symbol,
+                    package: entry.package,
+                    kind: entry.kind,
+                    ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+                    ...(entry.deprecated ? { deprecated: true } : {}),
+                });
             }
         }
     }
@@ -34,7 +149,10 @@ function searchSymbol(args, index) {
         content: [{
                 type: 'text',
                 text: `Found ${results.length} match(es) for '${query}':\n\n` +
-                    results.map(r => `  ${r.symbol} (${r.kind}) — ${r.package}`).join('\n'),
+                    results
+                        .map(r => `  ${r.symbol} (${r.kind}) — ${r.package}${r.deprecated ? ' [deprecated]' : ''}` +
+                        (r.signature ? `\n      ${r.signature}` : ''))
+                        .join('\n'),
             }],
     };
 }
@@ -44,17 +162,16 @@ function findType(args, index) {
         return { content: [{ type: 'text', text: 'pattern is required' }], isError: true };
     const results = [];
     for (const [pkgName, pkg] of Object.entries(index.packages)) {
-        for (const t of pkg.exports.interfaces) {
-            if (t.toLowerCase().includes(pattern))
-                results.push({ package: pkgName, type: t, kind: 'interface' });
-        }
-        for (const t of pkg.exports.types) {
-            if (t.toLowerCase().includes(pattern))
-                results.push({ package: pkgName, type: t, kind: 'type' });
-        }
-        for (const c of pkg.exports.classes) {
-            if (c.toLowerCase().includes(pattern))
-                results.push({ package: pkgName, type: c, kind: 'class' });
+        for (const entry of typeEntries(pkg)) {
+            if (entry.name.toLowerCase().includes(pattern)) {
+                results.push({
+                    package: pkgName,
+                    type: entry.name,
+                    kind: entry.kind,
+                    ...(entry.signature !== undefined ? { signature: entry.signature } : {}),
+                    ...(entry.deprecated ? { deprecated: true } : {}),
+                });
+            }
         }
     }
     results.sort((a, b) => a.type.localeCompare(b.type));
@@ -65,10 +182,31 @@ function findType(args, index) {
         content: [{
                 type: 'text',
                 text: `Found ${results.length} type(s) for '${pattern}':\n\n` +
-                    results.map(r => `  ${r.type} (${r.kind}) — ${r.package}`).join('\n'),
+                    results
+                        .map(r => `  ${r.type} (${r.kind}) — ${r.package}${r.deprecated ? ' [deprecated]' : ''}` +
+                        (r.signature ? `\n      ${r.signature}` : ''))
+                        .join('\n'),
             }],
     };
 }
+/** Type/interface/class entries for a package (uses `symbols` when present, else `exports`). */
+function typeEntries(pkg) {
+    if (pkg.symbols && Object.keys(pkg.symbols).length > 0) {
+        return Object.entries(pkg.symbols)
+            .filter(([, m]) => m.kind === 'type' || m.kind === 'interface' || m.kind === 'class')
+            .map(([name, m]) => ({
+            name,
+            kind: m.kind,
+            ...(m.signature !== undefined ? { signature: m.signature } : {}),
+            ...(m.deprecated ? { deprecated: true } : {}),
+        }));
+    }
+    return [
+        ...pkg.exports.interfaces.map(n => ({ name: n, kind: 'interface' })),
+        ...pkg.exports.types.map(n => ({ name: n, kind: 'type' })),
+        ...pkg.exports.classes.map(n => ({ name: n, kind: 'class' })),
+    ];
+}
 function dependencyGraph(args, index) {
     const pkgName = args.package;
     const direction = args.direction || 'out';
@@ -338,6 +476,40 @@ function scaffoldPackage(args) {
             }],
     };
 }
+function suggestTemplate(args) {
+    const usecase = (args.usecase || '').toLowerCase();
+    if (!usecase) {
+        return { content: [{ type: 'text', text: 'usecase is required — describe what you want to do (e.g. "time-lock funds until a block height")' }], isError: true };
+    }
+    const results = (0, template_catalog_js_1.searchTemplates)(usecase);
+    if (results.length === 0) {
+        return { content: [{ type: 'text', text: `No templates found matching '${usecase}'. Try different keywords (e.g. "lock", "vote", "payment", "identity", "state machine").` }] };
+    }
+    const lines = [`Found ${results.length} template(s) matching '${args.usecase}':`, ''];
+    for (const r of results) {
+        lines.push(`## ${r.template}`);
+        lines.push(`${r.description}`);
+        lines.push('');
+        lines.push(`**Functions:**`);
+        for (const fn of r.functions) {
+            lines.push(`  - \`import { ${fn} } from '@totemsdk/kissvm'\``);
+        }
+        if (r.configTypes.length > 0) {
+            lines.push('');
+            lines.push(`**Config types:**`);
+            for (const t of r.configTypes) {
+                lines.push(`  - \`${t}\``);
+            }
+        }
+        if (r.package) {
+            const pkgs = Array.isArray(r.package) ? r.package : [r.package];
+            lines.push('');
+            lines.push(`**Related package(s):** ${pkgs.map(p => `\`@totemsdk/${p}\``).join(', ')}`);
+        }
+        lines.push('');
+    }
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+}
 function packageStats(args, index) {
     const pkgName = args.name;
     if (!pkgName || !index.packages[pkgName]) {
@@ -348,6 +520,18 @@ function packageStats(args, index) {
         pkg.exports.classes.length + pkg.exports.interfaces.length + pkg.exports.consts.length;
     const totemDeps = pkg.dependencies.filter(d => d.startsWith('@totemsdk/'));
     const externalDeps = pkg.dependencies.filter(d => !d.startsWith('@totemsdk/'));
+    const pkgDir = pkg.name.replace('@totemsdk/', '');
+    const templates = (0, template_catalog_js_1.getTemplatesForPackage)(pkgDir);
+    const templateSection = templates.length > 0
+        ? [
+            ``,
+            `**KISSVM Templates:**`,
+            ...templates.flatMap(t => [
+                `  - **${t.template}** — ${t.description}`,
+                ...t.functions.map(fn => `    - \`import { ${fn} } from '@totemsdk/kissvm'\``),
+            ]),
+        ]
+        : [];
     return {
         content: [{
                 type: 'text',
@@ -371,6 +555,7 @@ function packageStats(args, index) {
                     `| Tests | ${pkg.hasTests ? 'Yes' : 'No'} |`,
                     `| @totemsdk/* deps | ${totemDeps.length} |`,
                     `| External deps | ${externalDeps.length} |`,
+                    ...templateSection,
                     ``,
                 ].join('\n'),
             }],
@@ -385,30 +570,36 @@ function listExports(args, index) {
     }
     const pkg = index.packages[pkgName];
     const sections = [];
+    const render = (s) => {
+        const m = pkg.symbols?.[s];
+        const dep = m?.deprecated ? ' · deprecated' : '';
+        return `  - \`${s}\`${dep}${m?.signature ? `\n      ${m.signature}` : ''}`;
+    };
+    const pick = (list) => (filter ? list.filter(s => s.toLowerCase().includes(filter)) : list);
     if (!kind || kind === 'function') {
-        const items = filter ? pkg.exports.functions.filter(s => s.toLowerCase().includes(filter)) : pkg.exports.functions;
+        const items = pick(pkg.exports.functions);
         if (items.length)
-            sections.push(`**Functions (${items.length}):**\n` + items.map(s => `  - \`${s}\``).join('\n'));
+            sections.push(`**Functions (${items.length}):**\n` + items.map(render).join('\n'));
     }
     if (!kind || kind === 'interface') {
-        const items = filter ? pkg.exports.interfaces.filter(s => s.toLowerCase().includes(filter)) : pkg.exports.interfaces;
+        const items = pick(pkg.exports.interfaces);
         if (items.length)
-            sections.push(`**Interfaces (${items.length}):**\n` + items.map(s => `  - \`${s}\``).join('\n'));
+            sections.push(`**Interfaces (${items.length}):**\n` + items.map(render).join('\n'));
     }
     if (!kind || kind === 'type') {
-        const items = filter ? pkg.exports.types.filter(s => s.toLowerCase().includes(filter)) : pkg.exports.types;
+        const items = pick(pkg.exports.types);
         if (items.length)
-            sections.push(`**Named Types (${items.length}):**\n` + items.map(s => `  - \`${s}\``).join('\n'));
+            sections.push(`**Named Types (${items.length}):**\n` + items.map(render).join('\n'));
     }
     if (!kind || kind === 'class') {
-        const items = filter ? pkg.exports.classes.filter(s => s.toLowerCase().includes(filter)) : pkg.exports.classes;
+        const items = pick(pkg.exports.classes);
         if (items.length)
-            sections.push(`**Classes (${items.length}):**\n` + items.map(s => `  - \`${s}\``).join('\n'));
+            sections.push(`**Classes (${items.length}):**\n` + items.map(render).join('\n'));
     }
     if (!kind || kind === 'const') {
-        const items = filter ? pkg.exports.consts.filter(s => s.toLowerCase().includes(filter)) : pkg.exports.consts;
+        const items = pick(pkg.exports.consts);
         if (items.length)
-            sections.push(`**Constants (${items.length}):**\n` + items.map(s => `  - \`${s}\``).join('\n'));
+            sections.push(`**Constants (${items.length}):**\n` + items.map(render).join('\n'));
     }
     return {
         content: [{ type: 'text', text: sections.join('\n\n') || `No exports found for '${pkgName}'` }],

package/dist/types.d.ts

@@ -3,12 +3,17 @@ export interface PackageIndex {
     dir: string;
     version: string;
     description: string;
+    keywords?: string[];
     dependencies: string[];
     devDependencies: string[];
     hasRust: boolean;
     hasGo: boolean;
     hasTests: boolean;
     exports: PackageExports;
+    /** Per-symbol metadata (signature, doc, deprecation) keyed by symbol name. */
+    symbols?: {
+        [name: string]: SymbolMeta;
+    };
     domain: string;
 }
 export interface PackageExports {
@@ -18,9 +23,22 @@ export interface PackageExports {
     interfaces: string[];
     consts: string[];
 }
+export type SymbolKind = 'function' | 'type' | 'class' | 'interface' | 'const' | 'variable';
+export interface SymbolMeta {
+    kind: SymbolKind;
+    /** Best-effort declaration text (params/return/extends), whitespace-normalized. */
+    signature?: string;
+    /** Leading JSDoc/line-comment text, if any. */
+    doc?: string;
+    /** True when the doc contains an `@deprecated` tag. */
+    deprecated?: boolean;
+}
 export interface SymbolEntry {
     package: string;
-    kind: 'function' | 'type' | 'class' | 'interface' | 'const' | 'variable';
+    kind: SymbolKind;
+    signature?: string;
+    doc?: string;
+    deprecated?: boolean;
 }
 export interface DomainMap {
     [domain: string]: string[];
@@ -35,6 +53,11 @@ export interface SdkIndex {
     };
     domainMap: DomainMap;
 }
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
 export interface ToolResponse {
     content: Array<{
         type: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@totemsdk/mcp-server",
-  "version": "0.1.0",
-  "description": "MCP server exposing the full Totem SDK package set — metadata, types, exports, dependency graphs, and scaffolding tools for 53 packages",
+  "version": "0.3.0",
+  "description": "MCP server exposing the full Totem SDK package set — metadata, types, exports, dependency graphs, and scaffolding tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
@@ -14,18 +14,20 @@
       "import": "./dist/index.js"
     }
   },
-  "scripts": {
-    "build": "tsc",
-    "prepare": "",
-    "clean": "rm -rf dist",
-    "start": "node dist/index.js"
-  },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.0.0",
     "typescript": "^7.0.2"
   },
   "engines": {
@@ -36,14 +38,26 @@
   },
   "license": "MIT",
   "author": "Totem SDK",
-  "homepage": "https://totem.ing",
+  "homepage": "https://docs.totem.ing",
   "bugs": {
-    "url": "https://github.com/totem-sdk/totem-sdk/issues"
+    "url": "https://github.com/Totem-Edge/totem-sdk/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/totem-sdk/totem-sdk.git",
-    "directory": "packages/totem-sdk/packages/mcp-server"
-  },
-  "keywords": ["totem", "totemsdk", "mcp", "model-context-protocol", "sdk-index"]
-}
+    "url": "git+https://github.com/Totem-Edge/totem-sdk.git",
+    "directory": "packages/mcp-server"
+  },
+  "keywords": [
+    "totem",
+    "totemsdk",
+    "mcp",
+    "model-context-protocol",
+    "sdk-index"
+  ],
+  "scripts": {
+    "build": "tsc && node ../../scripts/build-mcp-bundle.mjs",
+    "clean": "rm -rf dist data",
+    "start": "node dist/index.js",
+    "test": "jest"
+  }
+}