@totemsdk/mcp-server 0.2.0 → 0.4.0

package/dist/indexer.js

@@ -33,53 +33,93 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.IndexUnavailableError = void 0;
+exports.buildFromMonorepo = buildFromMonorepo;
 exports.buildIndex = buildIndex;
 exports.readSourceFile = readSourceFile;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
-function findRepoRoot() {
+/**
+ * Thrown when no SDK index can be produced — neither a monorepo to scan nor a
+ * bundled index shipped in the package. Callers must surface this as an error,
+ * never as an empty (and therefore confidently-wrong) index.
+ */
+class IndexUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IndexUnavailableError';
+    }
+}
+exports.IndexUnavailableError = IndexUnavailableError;
+/**
+ * Prebuilt index shipped in the published tarball (`data/sdk-index.json`), so
+ * the server works outside the monorepo. Generated by
+ * `scripts/build-mcp-bundle.mjs` at pack time.
+ */
+const BUNDLED_INDEX_PATH = path.join(__dirname, '..', 'data', 'sdk-index.json');
+/** A pnpm-workspace dir is only the SDK root if it actually contains the SDK. */
+function isSdkRoot(dir) {
+    return (fs.existsSync(path.join(dir, 'SDK_MANIFEST.json')) ||
+        fs.existsSync(path.join(dir, 'packages', 'core', 'package.json')));
+}
+/** Walk up from `__dirname` for a *valid* SDK root; `null` when not found. */
+function detectRepoRoot() {
     let dir = path.resolve(__dirname);
     while (dir !== path.dirname(dir)) {
-        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')))
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')) && isSdkRoot(dir))
             return dir;
         dir = path.dirname(dir);
     }
-    return dir;
-}
-const REPO_ROOT = findRepoRoot();
-const PKG_DIR = path.join(REPO_ROOT, 'packages', 'totem-sdk', 'packages');
-const TOP_PKG_DIR = path.join(REPO_ROOT, 'packages');
-const DOMAIN_GROUPS = [
-    [/^core-wasm$|^core$|^txpow$|^kissvm$/, 'core/crypto'],
-    [/^identity$|^root-identity$|^authority$|^proof$|^proof-integritas$|^proofgraph$|^manifest$/, 'identity/authority'],
-    [/^governance$|^recursive-mast$/, 'governance'],
-    [/^edge$|^edge-adapters$|^industrial-action$|^agent-policy$/, 'edge/runtime'],
-    [/^edge-(bacnet|ble|can|coap|email|grpc|lorawan|matter|modbus|mqtt|opcua|ros2)$/, 'edge/protocols'],
-    [/^omnia(-factory|-router|-splice|-vtxo|-host)?$/, 'blockchain/omnia'],
-    [/^statechain$|^tx-builder$|^chain-provider$|^wots-lease$|^liquidity-bond$|^provider-bond$/, 'blockchain/infra'],
-    [/^lookup-(client|node|protocol)$/, 'lookup/p2p'],
-    [/^stream-transport$|^pubsub-transport$|^minima-rpc$|^server$|^se-server$|^realtime$|^connect$|^wallet-adapter$|^pear$|^mcp-server$|^observability$/, 'utilities'],
-    [/^sdk-tests$/, 'testing'],
-];
-function classifyDomain(dirName) {
-    for (const [pattern, domain] of DOMAIN_GROUPS) {
-        if (pattern.test(dirName))
-            return domain;
-    }
-    return 'other';
-}
-function findPackageDirs() {
+    return null;
+}
+function loadRepoData(root) {
+    const topPkgDir = path.join(root, 'packages');
+    const manifest = new Map();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, 'SDK_MANIFEST.json'), 'utf-8'));
+        for (const pkg of parsed.packages ?? []) {
+            if (pkg && typeof pkg.name === 'string') {
+                manifest.set(pkg.name, { version: pkg.version, description: pkg.description, domain: pkg.domain });
+            }
+        }
+    }
+    catch {
+        // Manifest missing/unreadable — fall back to filesystem discovery only.
+    }
+    const ast = new Map();
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, 'scripts', 'mcp-symbols.ast.json'), 'utf-8'));
+        for (const [name, pkg] of Object.entries(parsed.packages ?? {})) {
+            if (pkg?.symbols)
+                ast.set(name, pkg.symbols);
+        }
+    }
+    catch {
+        // Optional artifact — fall back to the regex scan.
+    }
+    return { topPkgDir, manifest, ast };
+}
+function loadBundledIndex() {
+    try {
+        const idx = JSON.parse(fs.readFileSync(BUNDLED_INDEX_PATH, 'utf-8'));
+        if (idx && typeof idx === 'object' && idx.packages && typeof idx.packages === 'object')
+            return idx;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function findPackageDirs(TOP_PKG_DIR) {
     const dirs = [];
-    for (const base of [PKG_DIR, TOP_PKG_DIR]) {
-        if (!fs.existsSync(base))
+    if (!fs.existsSync(TOP_PKG_DIR))
+        return dirs;
+    for (const entry of fs.readdirSync(TOP_PKG_DIR, { withFileTypes: true })) {
+        if (!entry.isDirectory())
             continue;
-        for (const entry of fs.readdirSync(base, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const pj = path.join(base, entry.name, 'package.json');
-            if (fs.existsSync(pj))
-                dirs.push(path.join(base, entry.name));
-        }
+        const pj = path.join(TOP_PKG_DIR, entry.name, 'package.json');
+        if (fs.existsSync(pj))
+            dirs.push(path.join(TOP_PKG_DIR, entry.name));
     }
     return dirs.sort();
 }
@@ -96,66 +136,169 @@ function hasSubdir(dir, name) {
     return fs.existsSync(d) && fs.statSync(d).isDirectory();
 }
 function hasTestDir(dir) {
-    const srcTest = path.join(dir, 'src', '__tests__');
-    const srcTestAlt = path.join(dir, 'src', 'test');
-    const testDir = path.join(dir, 'test');
-    const testsDir = path.join(dir, 'tests');
-    return [srcTest, srcTestAlt, testDir, testsDir].some(d => fs.existsSync(d));
-}
-function parseExports(dir, pkgName) {
-    const indexFiles = [
-        path.join(dir, 'src', 'index.ts'),
-        path.join(dir, 'src', 'index.js'),
+    const candidates = [
+        path.join(dir, 'src', '__tests__'),
+        path.join(dir, 'src', 'test'),
+        path.join(dir, 'test'),
+        path.join(dir, 'tests'),
     ];
-    let content = '';
-    for (const f of indexFiles) {
-        if (fs.existsSync(f)) {
-            content = fs.readFileSync(f, 'utf-8');
+    return candidates.some(d => fs.existsSync(d));
+}
+function resolveModule(fromFile, spec) {
+    if (!spec.startsWith('.'))
+        return null;
+    const base = path.resolve(path.dirname(fromFile), spec.replace(/\.js$/, ''));
+    const candidates = [`${base}.ts`, `${base}.tsx`, path.join(base, 'index.ts')];
+    for (const c of candidates) {
+        if (fs.existsSync(c) && fs.statSync(c).isFile())
+            return c;
+    }
+    return null;
+}
+/** Leading JSDoc (`/** … *​/`) or contiguous `//` comment above a declaration. */
+function leadingDoc(lines, lineIndex) {
+    let j = lineIndex - 1;
+    while (j >= 0 && lines[j].trim() === '')
+        j--;
+    if (j < 0)
+        return {};
+    const t = lines[j].trim();
+    if (t.endsWith('*/')) {
+        const parts = [];
+        let k = j;
+        while (k >= 0) {
+            const line = lines[k].trim();
+            parts.unshift(line);
+            if (line.startsWith('/**') || line.startsWith('/*'))
+                break;
+            k--;
+        }
+        const raw = parts
+            .join('\n')
+            .replace(/^\/\*\*?/, '')
+            .replace(/\*\/$/, '')
+            .split('\n')
+            .map(l => l.replace(/^\s*\* ?/, ''))
+            .join('\n')
+            .trim();
+        const deprecated = /@deprecated/.test(raw);
+        const stripped = raw.replace(/@\w+[^\n]*/g, '').replace(/\n{2,}/g, '\n').trim();
+        return { doc: stripped || raw, ...(deprecated ? { deprecated } : {}) };
+    }
+    if (t.startsWith('//')) {
+        const parts = [];
+        let k = j;
+        while (k >= 0 && lines[k].trim().startsWith('//')) {
+            parts.unshift(lines[k].trim().replace(/^\/\/ ?/, ''));
+            k--;
+        }
+        const raw = parts.join('\n').trim();
+        return { doc: raw, ...(/@deprecated/.test(raw) ? { deprecated: true } : {}) };
+    }
+    return {};
+}
+/** Best-effort declaration text up to the body/terminator. */
+function captureSignature(lines, startIdx, stopAtBrace) {
+    let text = '';
+    for (let j = startIdx; j < Math.min(lines.length, startIdx + 8); j++) {
+        text += (j > startIdx ? ' ' : '') + lines[j].trim();
+        const brace = text.indexOf('{');
+        const semi = text.indexOf(';');
+        let cut = -1;
+        if (stopAtBrace) {
+            if (brace >= 0)
+                cut = brace;
+            else if (semi >= 0)
+                cut = semi;
+        }
+        else {
+            if (semi >= 0)
+                cut = semi;
+            else if (brace >= 0)
+                cut = brace;
+        }
+        if (cut >= 0) {
+            text = text.slice(0, cut);
             break;
         }
     }
-    const exports = { functions: [], types: [], classes: [], interfaces: [], consts: [] };
-    if (!content)
-        return exports;
+    return text.replace(/\s+/g, ' ').replace(/^export\s+/, '').replace(/[,\s]+$/, '').trim();
+}
+const KIND_TO_ARRAY = {
+    function: 'functions',
+    type: 'types',
+    class: 'classes',
+    interface: 'interfaces',
+    const: 'consts',
+    variable: 'consts',
+};
+function setSymbol(symbols, name, meta) {
+    if (name && !name.endsWith('}') && !symbols.has(name))
+        symbols.set(name, meta);
+}
+function collectExports(file, symbols, visited) {
+    if (visited.has(file))
+        return;
+    visited.add(file);
+    let content;
+    try {
+        content = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return;
+    }
     const lines = content.split('\n');
     let i = 0;
     while (i < lines.length) {
         const trimmed = lines[i].trim();
-        const fnMatch = trimmed.match(/^export (async )?function (\w+)/);
-        if (fnMatch) {
-            exports.functions.push(fnMatch[2]);
+        const starAsMatch = trimmed.match(/^export \* as (\w+) from ['"]([^'"]+)['"]/);
+        if (starAsMatch) {
+            setSymbol(symbols, starAsMatch[1], { kind: 'type', ...leadingDoc(lines, i) });
+            const target = resolveModule(file, starAsMatch[2]);
+            if (target)
+                collectExports(target, symbols, visited);
             i++;
             continue;
         }
-        const typeMatch = trimmed.match(/^export type \{ ([^}]+) \}/);
-        if (typeMatch) {
-            typeMatch[1].split(',').map(s => s.trim()).filter(Boolean).forEach(s => {
-                const name = s.split(/\s+as\s+/).pop()?.trim() || s;
-                if (name)
-                    exports.types.push(name);
-            });
+        const starMatch = trimmed.match(/^export \* from ['"]([^'"]+)['"]/);
+        if (starMatch) {
+            const target = resolveModule(file, starMatch[1]);
+            if (target)
+                collectExports(target, symbols, visited);
+            i++;
+            continue;
+        }
+        const fnMatch = trimmed.match(/^export (async )?function\*? (\w+)/);
+        if (fnMatch) {
+            setSymbol(symbols, fnMatch[2], { kind: 'function', signature: captureSignature(lines, i, true), ...leadingDoc(lines, i) });
             i++;
             continue;
         }
-        const clsMatch = trimmed.match(/^export class (\w+)/);
+        const clsMatch = trimmed.match(/^export (abstract )?class (\w+)/);
         if (clsMatch) {
-            exports.classes.push(clsMatch[1]);
+            setSymbol(symbols, clsMatch[2], { kind: 'class', signature: captureSignature(lines, i, true), ...leadingDoc(lines, i) });
             i++;
             continue;
         }
         const ifaceMatch = trimmed.match(/^export interface (\w+)/);
         if (ifaceMatch) {
-            exports.interfaces.push(ifaceMatch[1]);
+            setSymbol(symbols, ifaceMatch[1], { kind: 'interface', signature: captureSignature(lines, i, true), ...leadingDoc(lines, i) });
             i++;
             continue;
         }
         const constMatch = trimmed.match(/^export (const|let|var) (\w+)/);
         if (constMatch) {
-            exports.consts.push(constMatch[2]);
+            setSymbol(symbols, constMatch[2], { kind: 'const', signature: captureSignature(lines, i, false), ...leadingDoc(lines, i) });
             i++;
             continue;
         }
-        // Handle multi-line export { ... } from '...' blocks
+        const typeMatch = trimmed.match(/^export type (\w+)\s*[=<]/);
+        if (typeMatch) {
+            setSymbol(symbols, typeMatch[1], { kind: 'type', signature: captureSignature(lines, i, false), ...leadingDoc(lines, i) });
+            i++;
+            continue;
+        }
+        // Multi-line `export { ... }` / `export type { ... }` (inline or re-export).
         if (trimmed.startsWith('export {') || trimmed.startsWith('export type {')) {
             const isType = trimmed.startsWith('export type {');
             let block = trimmed;
@@ -164,22 +307,28 @@ function parseExports(dir, pkgName) {
                 j++;
                 block += ' ' + lines[j].trim();
             }
-            // Extract name list between { and }
             const braceMatch = block.match(/\{([^}]+)\}/);
             if (braceMatch) {
                 for (const part of braceMatch[1].split(',')) {
-                    const name = part.trim().split(/\s+as\s+/).pop()?.trim() || '';
-                    if (!name || name.endsWith('}'))
+                    let clause = part.trim();
+                    if (!clause)
                         continue;
-                    if (isType) {
-                        exports.types.push(name);
-                    }
-                    else {
-                        if (/^[A-Z]/.test(name))
-                            exports.types.push(name);
-                        else
-                            exports.functions.push(name);
+                    // Inline type modifiers: `export { type Foo }` / `export { type Foo as Bar }`.
+                    // Strip the leading `type` keyword before resolving the exposed name,
+                    // otherwise the symbol is recorded literally as "type Foo".
+                    let inlineType = false;
+                    const typeKw = clause.match(/^type\s+([\s\S]+)$/);
+                    if (typeKw) {
+                        inlineType = true;
+                        clause = typeKw[1].trim();
                     }
+                    const name = clause.split(/\s+as\s+/).pop()?.trim() || '';
+                    // Reject anything that isn't a plain identifier (guards against
+                    // malformed fragments leaking in as fake symbols).
+                    if (!/^[A-Za-z_$][\w$]*$/.test(name))
+                        continue;
+                    const kind = isType || inlineType || /^[A-Z]/.test(name) ? 'type' : 'function';
+                    setSymbol(symbols, name, { kind });
                 }
             }
             i = j + 1;
@@ -187,67 +336,142 @@ function parseExports(dir, pkgName) {
         }
         i++;
     }
+}
+function parseExports(dir) {
+    const symbols = new Map();
+    const candidates = [path.join(dir, 'src', 'index.ts'), path.join(dir, 'src', 'index.js')];
+    const entry = candidates.find(f => fs.existsSync(f));
+    if (entry)
+        collectExports(entry, symbols, new Set());
+    return symbols;
+}
+function exportsFromSymbols(symbols) {
+    const exports = { functions: [], types: [], classes: [], interfaces: [], consts: [] };
+    for (const [name, meta] of symbols)
+        exports[KIND_TO_ARRAY[meta.kind]].push(name);
     return exports;
 }
-function buildIndex() {
+/** Overlay exact AST metadata (authoritative) onto the regex-scanned symbols. */
+function mergeAst(symbols, ast) {
+    if (!ast)
+        return;
+    for (const [name, meta] of Object.entries(ast)) {
+        const existing = symbols.get(name);
+        symbols.set(name, { ...existing, ...meta, kind: meta.kind });
+    }
+}
+/** Scan a monorepo root into an `SdkIndex`. */
+function buildFromMonorepo(root, now = Date.now()) {
+    const { topPkgDir, manifest: MANIFEST, ast: AST } = loadRepoData(root);
     const packages = {};
     const symbolIndex = {};
     const domainMap = {};
-    for (const dir of findPackageDirs()) {
+    for (const dir of findPackageDirs(topPkgDir)) {
         const pkg = readPackageJson(dir);
         if (!pkg || !pkg.name)
             continue;
+        const manifest = MANIFEST.get(pkg.name);
+        if (MANIFEST.size > 0 && !manifest)
+            continue;
         const dirName = path.basename(dir);
-        const deps = Object.keys(pkg.dependencies || {});
-        const devDeps = Object.keys(pkg.devDependencies || {});
-        const hasRust = hasSubdir(dir, 'rust') || hasSubdir(dir, 'rust-toolchain');
-        const hasGo = hasSubdir(dir, 'go');
-        const hasTests = hasTestDir(dir);
-        const exports = parseExports(dir, pkg.name);
-        const domain = classifyDomain(dirName);
+        const symbols = parseExports(dir);
+        mergeAst(symbols, AST.get(pkg.name));
+        const exports = exportsFromSymbols(symbols);
+        const domain = manifest?.domain || 'other';
         const idx = {
             name: pkg.name,
             dir: dirName,
-            version: pkg.version || '0.0.0',
-            description: pkg.description || '',
-            dependencies: deps,
-            devDependencies: devDeps,
-            hasRust,
-            hasGo,
-            hasTests,
+            version: manifest?.version || pkg.version || '0.0.0',
+            description: manifest?.description || pkg.description || '',
+            ...(Array.isArray(pkg.keywords) ? { keywords: pkg.keywords } : {}),
+            dependencies: Object.keys(pkg.dependencies || {}),
+            devDependencies: Object.keys(pkg.devDependencies || {}),
+            hasRust: hasSubdir(dir, 'rust') || hasSubdir(dir, 'rust-toolchain'),
+            hasGo: hasSubdir(dir, 'go'),
+            hasTests: hasTestDir(dir),
             exports,
+            symbols: Object.fromEntries(symbols),
             domain,
         };
         packages[pkg.name] = idx;
         if (!domainMap[domain])
             domainMap[domain] = [];
         domainMap[domain].push(pkg.name);
-        const allExports = [];
-        for (const n of exports.functions)
-            allExports.push([n, 'function']);
-        for (const n of exports.types)
-            allExports.push([n, 'type']);
-        for (const n of exports.classes)
-            allExports.push([n, 'class']);
-        for (const n of exports.interfaces)
-            allExports.push([n, 'interface']);
-        for (const n of exports.consts)
-            allExports.push([n, 'const']);
-        for (const [name, kind] of allExports) {
-            if (!symbolIndex[name])
-                symbolIndex[name] = [];
-            symbolIndex[name].push({ package: pkg.name, kind });
-        }
-    }
-    return { generatedAt: Date.now(), packages, symbolIndex, domainMap };
+        for (const [name, meta] of symbols) {
+            (symbolIndex[name] ??= []).push({
+                package: pkg.name,
+                kind: meta.kind,
+                ...(meta.signature !== undefined ? { signature: meta.signature } : {}),
+                ...(meta.doc !== undefined ? { doc: meta.doc } : {}),
+                ...(meta.deprecated ? { deprecated: true } : {}),
+            });
+        }
+    }
+    return { generatedAt: now, packages, symbolIndex, domainMap };
 }
-function readSourceFile(pkgName, filePath) {
-    const relativePath = path.join('packages', 'totem-sdk', 'packages', pkgName, 'src', filePath);
-    const absPath = path.join(REPO_ROOT, relativePath);
-    const altPath = path.join(REPO_ROOT, 'packages', pkgName, 'src', filePath);
-    for (const p of [absPath, altPath]) {
-        if (fs.existsSync(p))
-            return fs.readFileSync(p, 'utf-8');
+/**
+ * Build the SDK index. Prefers a live monorepo scan; falls back to the bundled
+ * index shipped in the package. Throws {@link IndexUnavailableError} when
+ * neither is available — an empty index is never returned, because downstream
+ * tools would otherwise answer "not found" as if it were fact.
+ */
+function buildIndex(options = {}) {
+    const root = options.rootDir === undefined ? detectRepoRoot() : options.rootDir;
+    if (root)
+        return buildFromMonorepo(root);
+    if (!options.noBundled) {
+        const bundled = loadBundledIndex();
+        if (bundled)
+            return bundled;
     }
+    throw new IndexUnavailableError('@totemsdk/mcp-server: SDK index unavailable — not running inside the Totem SDK '
+        + 'monorepo and no bundled index was shipped. Reinstall @totemsdk/mcp-server '
+        + '(expected data/sdk-index.json) or run from the SDK repository.');
+}
+/** Map a package name (`@totemsdk/core`) or dir (`core`) to its absolute directory. */
+const _pkgDirCache = new Map();
+function packageDir(name) {
+    if (_pkgDirCache.has(name))
+        return _pkgDirCache.get(name) ?? null;
+    const root = detectRepoRoot();
+    if (!root) {
+        _pkgDirCache.set(name, null);
+        return null;
+    }
+    const TOP_PKG_DIR = path.join(root, 'packages');
+    const direct = path.join(TOP_PKG_DIR, name);
+    if (fs.existsSync(path.join(direct, 'package.json'))) {
+        _pkgDirCache.set(name, direct);
+        return direct;
+    }
+    if (fs.existsSync(TOP_PKG_DIR)) {
+        for (const entry of fs.readdirSync(TOP_PKG_DIR, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = path.join(TOP_PKG_DIR, entry.name);
+            const pj = path.join(dir, 'package.json');
+            if (!fs.existsSync(pj))
+                continue;
+            try {
+                if (JSON.parse(fs.readFileSync(pj, 'utf-8')).name === name) {
+                    _pkgDirCache.set(name, dir);
+                    return dir;
+                }
+            }
+            catch { /* ignore unreadable package.json */ }
+        }
+    }
+    _pkgDirCache.set(name, null);
     return null;
 }
+/** Read a file from a package's `src/` directory (for the `read-source` tool). */
+function readSourceFile(pkgName, filePath) {
+    const dir = packageDir(pkgName);
+    if (!dir)
+        return null;
+    const base = path.resolve(dir, 'src');
+    const resolved = path.resolve(base, filePath);
+    if (resolved !== base && !resolved.startsWith(base + path.sep))
+        return null;
+    return fs.existsSync(resolved) ? fs.readFileSync(resolved, 'utf-8') : null;
+}

package/dist/resources.d.ts

@@ -1,4 +1,8 @@
 import type { SdkIndex } from './types.js';
+/** Extract a markdown section by heading slug/text (for `totemsdk://rfc/014#6-design`). */
+export declare function extractSection(markdown: string, anchor: string): string | null;
+/** MIME type for a resource URI. */
+export declare function resourceMimeType(uri: string): string;
 export declare function handleResourceRead(uri: string, index: SdkIndex): string | null;
 export declare function listResources(index: SdkIndex): Array<{
     uri: string;