@totemsdk/mcp-server 0.2.0 → 0.4.0

package/dist/resources.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractSection = extractSection;
+exports.resourceMimeType = resourceMimeType;
 exports.handleResourceRead = handleResourceRead;
 exports.listResources = listResources;
 const template_catalog_js_1 = require("./template-catalog.js");
@@ -58,7 +60,7 @@ const PAPERS = [
     {
         uri: 'totemsdk://papers/red',
         name: 'Connect Red Paper',
-        description: 'dApp-wallet wire protocol specification — all 49 methods, every parameter, every response shape, error codes, security model',
+        description: 'dApp-wallet wire protocol specification — every method, parameter, response shape, error code and the security model',
         file: 'TOTEM_CONNECT_RED_PAPER.md',
     },
     {
@@ -81,11 +83,158 @@ const PAPERS = [
     },
     {
         uri: 'totemsdk://papers/gold',
-        name: 'Tokenomics Gold Paper',
-        description: 'Two-asset model — MINIMA as sovereign collateral backbone (Colour Coins, The Burn, Provider Bonds), TOTEM as service revenue token (staking, fee distribution, slashing, treasury)',
-        file: 'TOTEM_TOKENOMICS_GOLD_PAPER.md',
+        name: 'Network Economics Gold Paper',
+        description: 'Progressive decentralisation; MINIMA as settlement/native collateral where appropriate; $TOTEM as a potential network coordination and service-assurance asset (provider bonding, DAO stewardship, community-heavy genesis); no token assumed — network must earn the right to need one',
+        file: 'TOTEM_NETWORK_ECONOMICS_GOLD_PAPER.md',
+    },
+    {
+        uri: 'totemsdk://papers/purple',
+        name: 'Intelligence & Decision Purple Paper',
+        description: 'Bounded intelligence for autonomous systems — Intelligence vs Decision separation, bounded candidate spaces, the deterministic shell around probabilistic models, effective authority, governed Edge runtime, receipts and the Physical AI trust stack',
+        file: 'TOTEM_INTELLIGENCE_DECISION_PURPLE_PAPER.md',
     },
 ];
+/** Derive a name/description for a doc from its first heading + first paragraph. */
+function docMeta(file, fallbackName) {
+    const content = readRepoFile(file) ?? '';
+    const lines = content.split('\n');
+    const titleIdx = lines.findIndex(l => l.startsWith('# '));
+    const name = titleIdx >= 0 ? lines[titleIdx].replace(/^#\s+/, '').trim() : fallbackName;
+    let description = '';
+    for (let i = titleIdx + 1; i < lines.length; i++) {
+        const t = lines[i].trim();
+        if (!t || t.startsWith('#') || t.startsWith('**Status') || t.startsWith('---') || t.startsWith('>'))
+            continue;
+        description = t.replace(/[*_`]/g, '').trim();
+        break;
+    }
+    const clean = description || name || fallbackName;
+    // Cap at the first sentence / ~160 chars. Discovery must stay cheap: an
+    // unbounded first paragraph bloats every client's resource list.
+    const firstSentence = clean.split(/(?<=\.)\s/)[0];
+    const bounded = (firstSentence.length <= 160 ? firstSentence : clean.slice(0, 160)).trim();
+    return { name: name || fallbackName, description: bounded.length > 0 ? bounded : name || fallbackName };
+}
+/**
+ * RFCs and audits are discovered from disk, so a new `docs/rfc/RFC-*.md` or
+ * `docs/audits/*.md` is exposed automatically — there is no hand-maintained
+ * list to forget.
+ */
+function discoverDocs() {
+    const docs = [];
+    const rfcDir = path.join(REPO_ROOT, 'docs', 'rfc');
+    if (fs.existsSync(rfcDir)) {
+        for (const f of fs.readdirSync(rfcDir).sort()) {
+            const m = f.match(/^RFC-(\d+)-(.+)\.md$/);
+            if (!m)
+                continue;
+            const file = path.join('docs', 'rfc', f);
+            const meta = docMeta(file, `RFC-${m[1]}`);
+            // Amendments share an RFC number with the original; give them a distinct
+            // URI (`totemsdk://rfc/007/amendment-a`) so a reader never retrieves an
+            // amendment when they asked for the base specification.
+            const amend = m[2].match(/^AMENDMENT-([A-Z])/i);
+            const uri = amend
+                ? `totemsdk://rfc/${m[1]}/amendment-${amend[1].toLowerCase()}`
+                : `totemsdk://rfc/${m[1]}`;
+            docs.push({ uri, ...meta, file });
+        }
+    }
+    const auditDir = path.join(REPO_ROOT, 'docs', 'audits');
+    if (fs.existsSync(auditDir)) {
+        for (const f of fs.readdirSync(auditDir).sort()) {
+            if (!f.endsWith('.md'))
+                continue;
+            const base = f.replace(/\.md$/, '');
+            const slug = base.replace(/-\d{4}-\d{2}$/, '');
+            const file = path.join('docs', 'audits', f);
+            const meta = docMeta(file, base);
+            docs.push({ uri: `totemsdk://audit/${slug}`, ...meta, file });
+        }
+    }
+    // Worked, runnable end-to-end scenarios (usually backed by a test under
+    // packages/sdk-tests). Discovered from disk like RFCs/audits.
+    const exampleDir = path.join(REPO_ROOT, 'docs', 'examples');
+    if (fs.existsSync(exampleDir)) {
+        for (const f of fs.readdirSync(exampleDir).sort()) {
+            if (!f.endsWith('.md'))
+                continue;
+            const slug = f.replace(/\.md$/, '');
+            const file = path.join('docs', 'examples', f);
+            const meta = docMeta(file, slug);
+            docs.push({ uri: `totemsdk://example/${slug}`, ...meta, file });
+        }
+    }
+    return docs;
+}
+const DOCS = discoverDocs();
+/** Generated structured catalogs (parsed from source, not stored). */
+const CATALOGS = [
+    { uri: 'totemsdk://connect/methods', name: 'Connect Methods', description: 'The dApp-wallet wire protocol method catalog (@totemsdk/connect)' },
+    { uri: 'totemsdk://edge/capabilities', name: 'Edge Capabilities', description: 'Canonical EdgeCapability strings (@totemsdk/edge)' },
+    { uri: 'totemsdk://rfc', name: 'RFC Index', description: 'Index of SDK RFCs' },
+];
+function readRepoFile(rel) {
+    const p = path.join(REPO_ROOT, rel);
+    return fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : null;
+}
+function slugify(s) {
+    return s.toLowerCase().replace(/[`*_]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** Extract a markdown section by heading slug/text (for `totemsdk://rfc/014#6-design`). */
+function extractSection(markdown, anchor) {
+    const lines = markdown.split('\n');
+    const decoded = anchor.replace(/%20/g, ' ').toLowerCase();
+    let start = -1;
+    let level = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const m = lines[i].match(/^(#{1,6})\s+(.*)$/);
+        if (!m)
+            continue;
+        const text = m[2].trim();
+        if (slugify(text) === slugify(anchor) || text.toLowerCase().includes(decoded)) {
+            start = i;
+            level = m[1].length;
+            break;
+        }
+    }
+    if (start < 0)
+        return null;
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        const m = lines[i].match(/^(#{1,6})\s+/);
+        if (m && m[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end).join('\n').trim();
+}
+function connectMethods() {
+    const src = readRepoFile(path.join('packages', 'connect', 'src', 'index.ts'));
+    if (!src)
+        return [];
+    return [...new Set([...src.matchAll(/method:\s*'([A-Za-z_]+)'/g)].map(m => m[1]))].sort();
+}
+function edgeCapabilities() {
+    const src = readRepoFile(path.join('packages', 'edge', 'src', 'capabilities.ts'));
+    if (!src)
+        return [];
+    return [...new Set([...src.matchAll(/'([a-z][a-z0-9-]*:[a-z0-9-]+)'/g)].map(m => m[1]))].sort();
+}
+/** MIME type for a resource URI. */
+function resourceMimeType(uri) {
+    const base = uri.split('#')[0];
+    if (base === 'totemsdk://conventions' || base === 'totemsdk://templates')
+        return 'text/markdown';
+    if (/^totemsdk:\/\/(papers|rfc|audit|example)\/[^/]+(\/[^/]+)?$/.test(base))
+        return 'text/markdown';
+    if (base === 'totemsdk://packages' || base === 'totemsdk://domain-map' || base === 'totemsdk://rfc')
+        return 'application/json';
+    if (/^totemsdk:\/\/(packages|symbol|connect|edge)(\/|$)/.test(base))
+        return 'application/json';
+    return 'text/plain';
+}
 const CONVENTIONS = `# Totem SDK Conventions
 
 ## Package Structure
@@ -103,11 +252,11 @@ const CONVENTIONS = `# Totem SDK Conventions
 ## Canonical JSON
 - Recursive deterministic JSON with sorted object keys
 - Used as input to all hashing and signing operations
-- Each package has its own canonicalJson() (no shared util)
+- Shared: import { canonicalJson, hashCanonical, toHex, sha3_256 } from '@totemsdk/core'
 
 ## Hashing
 - SHA3-256 via @totemsdk/core
-- Domain-prefixed: sha3-256(domain + canonicalJson(data))
+- Domain-separated: hashCanonical('<DOMAIN>_V1', data) == sha3-256(domain + canonicalJson(data))
 - Domain constants like 'TOTEM_GOVERNANCE_PROPOSAL_V1'
 
 ## Signing
@@ -130,17 +279,26 @@ const CONVENTIONS = `# Totem SDK Conventions
 - Promise<T> everywhere, typed event emitters, no Observables
 - Action lifecycle: propose -> reserve -> execute -> confirm/fail/unknown`;
 function handleResourceRead(uri, index) {
-    const paperMatch = uri.match(/^totemsdk:\/\/papers\/(\w+)$/);
-    if (paperMatch) {
-        const paper = PAPERS.find(p => p.uri === uri);
-        if (paper) {
-            const filePath = path.join(REPO_ROOT, paper.file);
-            if (fs.existsSync(filePath)) {
-                return fs.readFileSync(filePath, 'utf-8');
-            }
-            return `Paper file not found: ${paper.file}`;
+    if (uri === 'totemsdk://connect/methods')
+        return JSON.stringify(connectMethods(), null, 2);
+    if (uri === 'totemsdk://edge/capabilities')
+        return JSON.stringify(edgeCapabilities(), null, 2);
+    if (uri === 'totemsdk://rfc') {
+        return JSON.stringify(DOCS.filter(d => d.uri.startsWith('totemsdk://rfc/')).map(d => ({ uri: d.uri, name: d.name, description: d.description })), null, 2);
+    }
+    const base = uri.split('#')[0];
+    const readable = [...PAPERS, ...DOCS].find(d => d.uri === base);
+    if (readable) {
+        const filePath = path.join(REPO_ROOT, readable.file);
+        if (!fs.existsSync(filePath))
+            return `Document not found: ${readable.file}`;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const hash = uri.indexOf('#');
+        if (hash >= 0) {
+            const section = extractSection(content, uri.slice(hash + 1));
+            return section ?? `Section not found: ${uri.slice(hash + 1)}`;
         }
-        return null;
+        return content;
     }
     if (uri === 'totemsdk://packages') {
         return JSON.stringify(Object.values(index.packages).map(p => ({
@@ -203,10 +361,12 @@ function handleResourceRead(uri, index) {
 function listResources(index) {
     const resources = [
         { uri: 'totemsdk://packages', name: 'All Packages', description: `List of all ${Object.keys(index.packages).length} SDK packages with metadata` },
-        { uri: 'totemsdk://templates', name: 'All KISSVM Templates', description: 'All 45 KISSVM script templates with import paths and descriptions' },
+        { uri: 'totemsdk://templates', name: 'All KISSVM Templates', description: `All ${(0, template_catalog_js_1.getAllTemplates)().length} KISSVM script templates with import paths and descriptions` },
         { uri: 'totemsdk://conventions', name: 'Coding Conventions', description: 'Totem SDK coding conventions and patterns' },
         { uri: 'totemsdk://domain-map', name: 'Domain Map', description: 'Packages grouped by domain layer' },
         ...PAPERS.map(p => ({ uri: p.uri, name: p.name, description: p.description })),
+        ...DOCS.map(d => ({ uri: d.uri, name: d.name, description: d.description })),
+        ...CATALOGS,
     ];
     for (const [domain, pkgs] of Object.entries(index.domainMap)) {
         resources.push({
@@ -232,10 +392,16 @@ function listResources(index) {
             description: `Dependencies of ${name}`,
         });
     }
-    const topSymbols = Object.entries(index.symbolIndex)
-        .filter(([_, v]) => v.length <= 3)
-        .slice(0, 200);
-    for (const [symbol, entries] of topSymbols) {
+    // Symbol lookups are served by the `search-symbol` tool (query-driven), which
+    // is far cheaper than enumerating ~3.7k symbols as resources. Only surface a
+    // small set of the most unambiguous symbols (exported by exactly one package)
+    // so `totemsdk://symbol/{name}` remains discoverable without bloating
+    // discovery to hundreds of entries.
+    const uniqueSymbols = Object.entries(index.symbolIndex)
+        .filter(([_, v]) => v.length === 1)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .slice(0, 50);
+    for (const [symbol, entries] of uniqueSymbols) {
         resources.push({
             uri: `totemsdk://symbol/${symbol}`,
             name: `Symbol: ${symbol}`,

package/dist/tools.d.ts

@@ -1,2 +1,8 @@
-import type { SdkIndex, ToolResponse } from './types.js';
+import type { SdkIndex, ToolDefinition, ToolResponse } from './types.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.
+ */
+export declare const TOOL_DEFINITIONS: ToolDefinition[];
 export declare function handleToolCall(name: string, args: any, index: SdkIndex): ToolResponse;

package/dist/tools.js

@@ -1,7 +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);
@@ -13,9 +36,93 @@ function handleToolCall(name, args, index) {
         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)
@@ -24,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 } : {}),
+                });
             }
         }
     }
@@ -36,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'),
             }],
     };
 }
@@ -46,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));
@@ -67,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';
@@ -434,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.2.0",
-  "description": "MCP server exposing the full Totem SDK package set — metadata, types, exports, dependency graphs, and scaffolding tools for 55 packages",
+  "version": "0.4.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": {
@@ -16,6 +16,7 @@
   },
   "files": [
     "dist",
+    "data",
     "README.md",
     "LICENSE"
   ],
@@ -37,7 +38,7 @@
   },
   "license": "MIT",
   "author": "Totem SDK",
-  "homepage": "https://totem.ing",
+  "homepage": "https://docs.totem.ing",
   "bugs": {
     "url": "https://github.com/Totem-Edge/totem-sdk/issues"
   },
@@ -54,8 +55,8 @@
     "sdk-index"
   ],
   "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
+    "build": "tsc && node ../../scripts/build-mcp-bundle.mjs",
+    "clean": "rm -rf dist data",
     "start": "node dist/index.js",
     "test": "jest"
   }