@papyruslabsai/seshat-mcp 0.20.0 → 0.20.1

package/dist/tools/index.d.ts

@@ -1,66 +0,0 @@
-/**
- * Semantic MCP Tool Implementations
- *
- * Each tool exposes a query or computation over the extracted code entity graph.
- * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
- *
- * Multi-project: when multiple projects are loaded, each tool accepts an optional
- * `project` parameter. In multi-project mode, `project` is required.
- */
-import type { JstfEntity, ProjectLoader } from '../types.js';
-import { type CallGraph } from '../graph.js';
-export { extractDbOps, tableContract, type DbOperation } from './dbops.js';
-export declare function getGraph(project: string | undefined, loader: ProjectLoader): CallGraph;
-/**
- * Validate project param. Returns error string if invalid, null if OK.
- * In single-project mode, project is optional (defaults to the only project).
- * In multi-project mode, project is required.
- */
-export declare function validateProject(project: string | undefined, loader: ProjectLoader): string | null;
-export declare function entityName(e: JstfEntity): string;
-export declare function entityLayer(e: JstfEntity): string;
-export declare function entitySummary(e: JstfEntity): Record<string, unknown>;
-export declare function normalizeConstraints(constraints: JstfEntity['constraints']): string[];
-/**
- * Deep search constraints — matches against raw constraint object fields too,
- * not just normalized tags.
- */
-export declare function constraintMatches(constraints: JstfEntity['constraints'], target: string): boolean;
-export declare function queryEntities(args: {
-    project?: string;
-    query?: string;
-    layer?: string;
-    module?: string;
-    language?: string;
-    limit?: number;
-}, loader: ProjectLoader): Promise<unknown>;
-export declare function getEntity(args: {
-    id: string;
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function getDependencies(args: {
-    entity_id: string;
-    direction?: 'callers' | 'callees' | 'both';
-    depth?: number;
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function collectTransitive(adjacency: Map<string, Set<string>>, startId: string, maxDepth: number): string[];
-export declare function getDataFlow(args: {
-    entity_id: string;
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function findByConstraint(args: {
-    constraint: string;
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function getBlastRadius(args: {
-    entity_ids: string[];
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function listModules(args: {
-    group_by?: 'layer' | 'module' | 'file' | 'language';
-    project?: string;
-}, loader: ProjectLoader): unknown;
-export declare function getTopology(args: {
-    project?: string;
-} | undefined, loader: ProjectLoader): unknown;

package/dist/tools/index.js

@@ -1,389 +0,0 @@
-/**
- * Semantic MCP Tool Implementations
- *
- * Each tool exposes a query or computation over the extracted code entity graph.
- * Tools operate on the in-memory entity bundle loaded from .seshat/_bundle.json.
- *
- * Multi-project: when multiple projects are loaded, each tool accepts an optional
- * `project` parameter. In multi-project mode, `project` is required.
- */
-import { buildCallGraph, computeBlastRadius } from '../graph.js';
-export { extractDbOps, tableContract } from './dbops.js';
-export function getGraph(project, loader) {
-    // Fast path: use pre-computed call graph edges cached on the snapshot row
-    // (avoids 3-10s CPU rebuild on first request for large codebases)
-    const precomputed = loader.getPrecomputedGraph?.();
-    if (precomputed)
-        return precomputed;
-    // Fallback for old snapshots (NULL call_graph_edges) or local file loaders
-    return buildCallGraph(loader.getEntities(project));
-}
-/**
- * Validate project param. Returns error string if invalid, null if OK.
- * In single-project mode, project is optional (defaults to the only project).
- * In multi-project mode, project is required.
- */
-export function validateProject(project, loader) {
-    if (!loader.isMultiProject())
-        return null; // single project, always OK
-    if (!project) {
-        return `Multiple projects loaded. You must specify a "project" parameter. Available: ${loader.getProjectNames().join(', ')}`;
-    }
-    if (!loader.hasProject(project)) {
-        return `Project "${project}" not found. Available: ${loader.getProjectNames().join(', ')}`;
-    }
-    return null;
-}
-// ─── Helper: Extract entity name from struct ─────────────────────
-export function entityName(e) {
-    if (typeof e.struct === 'string')
-        return e.struct;
-    return e.struct?.name || e.id || 'anonymous';
-}
-export function entityLayer(e) {
-    // Use explicit layer if specific enough
-    const explicit = e.context?.layer?.toLowerCase();
-    if (explicit && explicit !== 'module' && explicit !== 'unknown')
-        return explicit;
-    // Infer from source file path (matches extract-and-generate.mjs logic)
-    const src = (e._sourceFile || e.context?.module || '').toLowerCase().replace(/\\/g, '/');
-    if (src.includes('/route') || src.includes('/api/'))
-        return 'route';
-    if (src.includes('/controller'))
-        return 'controller';
-    if (src.includes('/service'))
-        return 'service';
-    if (src.includes('/repo') || src.includes('/database') || src.includes('/db/'))
-        return 'repository';
-    if (src.includes('/util') || src.includes('/helper') || src.includes('/lib/'))
-        return 'utility';
-    if (src.includes('/hook'))
-        return 'hook';
-    if (src.includes('/component') || src.includes('/ui/'))
-        return 'component';
-    if (src.includes('/middleware'))
-        return 'middleware';
-    if (src.includes('/model') || src.includes('/entity'))
-        return 'model';
-    if (src.includes('/schema') || explicit === 'schema')
-        return 'schema';
-    if (src.includes('/test/') || src.includes('/tests/') || src.includes('/__tests__/') ||
-        src.includes('.test.') || src.includes('.spec.'))
-        return 'test';
-    return explicit || 'other';
-}
-export function entitySummary(e) {
-    const constraintTags = normalizeConstraints(e.constraints);
-    return {
-        id: e.id,
-        name: entityName(e),
-        ...(e._project ? { project: e._project } : {}),
-        layer: entityLayer(e),
-        module: e.context?.module || null,
-        sourceFile: e._sourceFile || null,
-        line: e._sourceLine ?? undefined,
-        sourceLanguage: e._sourceLanguage || null,
-        async: typeof e.struct !== 'string' ? e.struct?.async : undefined,
-        exported: typeof e.struct !== 'string' ? e.struct?.exported : undefined,
-        constraints: constraintTags.length > 0 ? constraintTags : undefined,
-        callExpressions: Array.isArray(e.edges?.calls) ? e.edges.calls.length : 0,
-        uniqueCallees: Array.isArray(e.edges?.calls)
-            ? new Set(e.edges.calls.map(c => c.target)).size
-            : 0,
-    };
-}
-export function normalizeConstraints(constraints) {
-    if (!constraints)
-        return [];
-    if (Array.isArray(constraints))
-        return constraints.map(String);
-    if (typeof constraints === 'object') {
-        const tags = [];
-        const c = constraints;
-        // Tag-based format: { security: ["AUTH", "VALIDATED"] }
-        if (c.security && Array.isArray(c.security))
-            tags.push(...c.security.map(String));
-        if (c.validation && Array.isArray(c.validation) && c.validation.length > 0) {
-            tags.push('VALIDATED');
-        }
-        // Property-based format: { purity: "pure"|"impure", immutable: true, sideEffects: [...] }
-        if (c.purity === 'pure')
-            tags.push('PURE');
-        if (c.purity === 'impure')
-            tags.push('IMPURE');
-        if (c.immutable)
-            tags.push('IMMUTABLE');
-        if (c.throws)
-            tags.push('THROWS');
-        if (Array.isArray(c.sideEffects)) {
-            for (const effect of c.sideEffects) {
-                if (typeof effect === 'string') {
-                    if (effect === 'network')
-                        tags.push('NETWORK_IO');
-                    else if (effect === 'db' || effect === 'database')
-                        tags.push('DB_ACCESS');
-                    else if (effect === 'filesystem' || effect === 'fs')
-                        tags.push('FS_ACCESS');
-                    else
-                        tags.push(effect.toUpperCase());
-                }
-            }
-        }
-        if (c.nullSafety)
-            tags.push('NULL_SAFE');
-        if (c.performance) {
-            const perf = c.performance;
-            if (perf.dbCalls)
-                tags.push('DB_ACCESS');
-            if (perf.apiCalls)
-                tags.push('NETWORK_IO');
-        }
-        return tags;
-    }
-    return [];
-}
-/**
- * Deep search constraints — matches against raw constraint object fields too,
- * not just normalized tags.
- */
-export function constraintMatches(constraints, target) {
-    // First check normalized tags
-    const tags = normalizeConstraints(constraints);
-    if (tags.some((t) => t.toUpperCase().includes(target.toUpperCase())))
-        return true;
-    // Also search raw constraint values for substring match
-    if (constraints && typeof constraints === 'object' && !Array.isArray(constraints)) {
-        const str = JSON.stringify(constraints).toLowerCase();
-        if (str.includes(target.toLowerCase()))
-            return true;
-    }
-    return false;
-}
-// ─── Tool: query_entities ─────────────────────────────────────────
-export async function queryEntities(args, loader) {
-    const apiKey = process.env.SESHAT_API_KEY;
-    if (!apiKey) {
-        return { error: 'SESHAT_API_KEY environment variable is missing. You must provide an API key to use Ptah Cloud tools.' };
-    }
-    // We are hardcoding the project_hash to 'seshat-fabric' for this local test, 
-    // but in production the MCP would pass args.project or read from the manifest.
-    const project_hash = args.project || 'seshat-fabric';
-    try {
-        const res = await fetch('http://localhost:3001/api/mcp/execute', {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                'x-api-key': apiKey
-            },
-            body: JSON.stringify({
-                tool: 'query_entities',
-                project_hash: project_hash,
-                args
-            })
-        });
-        if (!res.ok) {
-            const errorText = await res.text();
-            return { error: `Cloud API Error (${res.status}): ${errorText}` };
-        }
-        return await res.json();
-    }
-    catch (error) {
-        return { error: `Failed to connect to Ptah Cloud: ${error.message}` };
-    }
-}
-// ─── Tool: get_entity ─────────────────────────────────────────────
-export function getEntity(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entity = loader.getEntityById(args.id, args.project) || loader.getEntityByName(args.id, args.project);
-    if (!entity) {
-        return { error: `Entity not found: ${args.id}` };
-    }
-    return {
-        id: entity.id,
-        name: entityName(entity),
-        ...(entity._project ? { project: entity._project } : {}),
-        sourceFile: entity._sourceFile,
-        sourceLanguage: entity._sourceLanguage,
-        structure: entity.struct,
-        call_graph: entity.edges,
-        data_flow: entity.data,
-        constraints: entity.constraints,
-        context: entity.context,
-        ownership: entity.ownership,
-        type_info: entity.traits,
-        runtime: entity.runtime,
-        logic: entity.semantics,
-    };
-}
-// ─── Tool: get_dependencies ───────────────────────────────────────
-export function getDependencies(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { entity_id, direction = 'both', depth = 2 } = args;
-    const g = getGraph(args.project, loader);
-    const entity = loader.getEntityById(entity_id, args.project) || loader.getEntityByName(entity_id, args.project);
-    if (!entity) {
-        return { error: `Entity not found: ${entity_id}` };
-    }
-    const id = entity.id;
-    const result = {
-        entity: { id, name: entityName(entity) },
-    };
-    if (direction === 'callers' || direction === 'both') {
-        const callerIds = collectTransitive(g.callers, id, depth);
-        result.callers = callerIds.map(cId => {
-            const e = g.entityById.get(cId);
-            return e ? entitySummary(e) : { id: cId };
-        });
-    }
-    if (direction === 'callees' || direction === 'both') {
-        const calleeIds = collectTransitive(g.callees, id, depth);
-        result.callees = calleeIds.map(cId => {
-            const e = g.entityById.get(cId);
-            return e ? entitySummary(e) : { id: cId };
-        });
-    }
-    // Also include direct imports
-    if (entity.edges?.imports) {
-        result.imports = entity.edges.imports;
-    }
-    return result;
-}
-export function collectTransitive(adjacency, startId, maxDepth) {
-    const visited = new Set();
-    const queue = [[startId, 0]];
-    visited.add(startId);
-    while (queue.length > 0) {
-        const [current, d] = queue.shift();
-        if (d >= maxDepth)
-            continue;
-        const neighbors = adjacency.get(current);
-        if (!neighbors)
-            continue;
-        for (const neighbor of neighbors) {
-            if (!visited.has(neighbor)) {
-                visited.add(neighbor);
-                queue.push([neighbor, d + 1]);
-            }
-        }
-    }
-    visited.delete(startId); // Don't include the start entity itself
-    return [...visited];
-}
-// ─── Tool: get_data_flow ──────────────────────────────────────────
-export function getDataFlow(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const entity = loader.getEntityById(args.entity_id, args.project) || loader.getEntityByName(args.entity_id, args.project);
-    if (!entity) {
-        return { error: `Entity not found: ${args.entity_id}` };
-    }
-    return {
-        entity: { id: entity.id, name: entityName(entity) },
-        inputs: entity.data?.inputs || entity.data?.sources || [],
-        outputs: entity.data?.outputs || entity.data?.returns || [],
-        mutations: entity.data?.mutations || [],
-    };
-}
-// ─── Tool: find_by_constraint ─────────────────────────────────────
-export function findByConstraint(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const target = args.constraint;
-    const results = loader.getEntities(args.project).filter((e) => constraintMatches(e.constraints, target));
-    return {
-        constraint: args.constraint,
-        total: results.length,
-        entities: results.slice(0, 100).map(entitySummary),
-    };
-}
-// ─── Tool: get_blast_radius ───────────────────────────────────────
-export function getBlastRadius(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const g = getGraph(args.project, loader);
-    // Resolve names to IDs
-    const resolvedIds = new Set();
-    const notFound = [];
-    for (const nameOrId of args.entity_ids) {
-        const entity = loader.getEntityById(nameOrId, args.project) || loader.getEntityByName(nameOrId, args.project);
-        if (entity) {
-            resolvedIds.add(entity.id);
-        }
-        else {
-            notFound.push(nameOrId);
-        }
-    }
-    if (resolvedIds.size === 0) {
-        return { error: `No entities found for: ${args.entity_ids.join(', ')}` };
-    }
-    const result = computeBlastRadius(g, resolvedIds);
-    return {
-        changed: [...resolvedIds],
-        totalAffected: result.affected.length,
-        ancestors: result.ancestors.length,
-        descendants: result.descendants.length,
-        affected: result.affected.slice(0, 100).map(id => {
-            const e = g.entityById.get(id);
-            return {
-                ...(e ? entitySummary(e) : { id }),
-                depth: result.depthMap[id],
-            };
-        }),
-        ...(notFound.length > 0 ? { notFound } : {}),
-    };
-}
-// ─── Tool: list_modules ───────────────────────────────────────────
-export function listModules(args, loader) {
-    const projErr = validateProject(args.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const { group_by = 'layer' } = args;
-    const entities = loader.getEntities(args.project);
-    const groups = new Map();
-    for (const e of entities) {
-        let key;
-        switch (group_by) {
-            case 'layer':
-                key = entityLayer(e);
-                break;
-            case 'module':
-                key = e.context?.module || 'unknown';
-                break;
-            case 'file':
-                key = e._sourceFile || 'unknown';
-                break;
-            case 'language':
-                key = e._sourceLanguage || 'unknown';
-                break;
-            default:
-                key = entityLayer(e);
-        }
-        groups.set(key, (groups.get(key) || 0) + 1);
-    }
-    // Sort by count descending
-    const sorted = [...groups.entries()].sort((a, b) => b[1] - a[1]);
-    return {
-        groupBy: group_by,
-        totalEntities: entities.length,
-        groupCount: sorted.length,
-        groups: Object.fromEntries(sorted),
-    };
-}
-// ─── Tool: get_topology ───────────────────────────────────────────
-export function getTopology(args, loader) {
-    const projErr = validateProject(args?.project, loader);
-    if (projErr)
-        return { error: projErr };
-    const topology = loader.getTopology(args?.project);
-    if (!topology) {
-        return { error: 'No topology data found. The _topology.json file may not have been generated.' };
-    }
-    return topology;
-}

package/dist/types.d.ts

@@ -1,174 +0,0 @@
-/**
- * Code Entity — the core unit of analysis
- *
- * Each entity represents a code unit (function, class, module, schema)
- * with extracted properties: structure, call graph, data flow, constraints,
- * context, ownership, type info, runtime, and logic.
- */
-export interface JstfEntity {
-    id: string;
-    _jstfFilename?: string;
-    _sourceFile?: string | null;
-    _sourceLanguage?: string;
-    _project?: string;
-    _sourceLocation?: {
-        startLine: number;
-        endLine: number;
-    };
-    /** Structure: function shape, signature, modifiers */
-    struct?: {
-        name?: string;
-        type?: string;
-        async?: boolean;
-        exported?: boolean;
-        params?: Array<{
-            name: string;
-            type?: string;
-        }>;
-        returnType?: string;
-        [key: string]: unknown;
-    } | string;
-    /** Call graph: dependencies, imports, callers */
-    edges?: {
-        calls?: Array<{
-            target: string;
-            type?: string;
-        }>;
-        imports?: Array<{
-            module: string;
-            bindings?: string[];
-        }>;
-        calledBy?: Array<{
-            source: string;
-            type?: string;
-        }>;
-        [key: string]: unknown;
-    };
-    /** Data flow: inputs, outputs, mutations */
-    data?: {
-        inputs?: Array<{
-            name: string;
-            source?: string;
-            untrusted?: boolean;
-        }>;
-        outputs?: Array<{
-            name: string;
-            destination?: string;
-        }>;
-        mutations?: Array<{
-            target: string;
-            operation?: string;
-        }>;
-        tables?: string[];
-        sources?: unknown[];
-        returns?: unknown[];
-        [key: string]: unknown;
-    };
-    /** Constraints: behavioral contracts, validation, purity */
-    constraints?: {
-        security?: string[];
-        performance?: Record<string, unknown>;
-        validation?: Array<{
-            field: string;
-            rule: string;
-        }>;
-        auth?: string[] | 'none';
-        authRequired?: boolean;
-        purity?: string;
-        throws?: boolean;
-        sideEffects?: string[];
-        errorHandling?: {
-            tryCatch?: boolean;
-            catchClause?: boolean;
-            finally?: boolean;
-            errorBoundary?: boolean;
-        };
-        [key: string]: unknown;
-    } | string[];
-    /** Context: architectural position, visibility, layer */
-    context?: {
-        layer?: string;
-        layerSource?: string;
-        module?: string;
-        path?: string;
-        exposure?: string;
-        visibility?: string;
-        traffic?: string;
-        criticality?: string;
-        [key: string]: unknown;
-    };
-    /** Ownership: memory management, lifetimes, borrowing (Rust/C++) */
-    ownership?: Record<string, unknown>;
-    /** Type info: type capabilities, bounds, markers */
-    traits?: string[] | {
-        self?: {
-            asyncContext?: boolean;
-            fallible?: boolean;
-            [key: string]: unknown;
-        };
-        params?: Record<string, {
-            bounds?: string[];
-            markers?: string[];
-        }>;
-        [key: string]: unknown;
-    };
-    /** Runtime: async model, platform, framework */
-    runtime?: {
-        async?: string;
-        framework?: string;
-        platform?: string;
-        [key: string]: unknown;
-    };
-    /** Logic: operational content, normalized logic tree */
-    semantics?: unknown[];
-    [key: string]: unknown;
-}
-export interface JstfBundle {
-    $schema: string;
-    extractedAt: string;
-    source: string;
-    files: number;
-    languages: string[];
-    entityCount: number;
-    entities: JstfEntity[];
-}
-export interface Topology {
-    stats: {
-        plugins: number;
-        routes: number;
-        tables: number;
-        authRequired: number;
-    };
-    [key: string]: unknown;
-}
-export interface Manifest {
-    projectName: string;
-    commitSha: string;
-    extractedAt: string;
-    entityCount: number;
-    languages: string[];
-    layers: Record<string, number>;
-}
-export interface ProjectInfo {
-    name: string;
-    path: string;
-    entityCount: number;
-    languages: string[];
-    commitSha: string;
-    extractedAt: string;
-    layers: Record<string, number>;
-}
-export interface ProjectLoader {
-    getEntities(project?: string): JstfEntity[];
-    getTopology(project?: string): Topology | null;
-    getManifest(project?: string): Manifest | null;
-    getEntityById(id: string, project?: string): JstfEntity | undefined;
-    getEntityByName(name: string, project?: string): JstfEntity | undefined;
-    getProjectNames(): string[];
-    getProjectInfo(): ProjectInfo[];
-    isMultiProject(): boolean;
-    isLoaded(): boolean;
-    hasProject(name: string): boolean;
-    registerVirtualEntity(entity: JstfEntity, project?: string): void;
-    totalEntities(): number;
-}

package/dist/types.js

@@ -1,8 +0,0 @@
-/**
- * Code Entity — the core unit of analysis
- *
- * Each entity represents a code unit (function, class, module, schema)
- * with extracted properties: structure, call graph, data flow, constraints,
- * context, ownership, type info, runtime, and logic.
- */
-export {};