weavatrix 0.2.19 → 0.3.1

package/src/mcp/catalog.mjs

@@ -8,21 +8,18 @@ import {fileURLToPath} from 'node:url'
 import {resolveNode, isSymbol, stalenessLine, resetStalenessCache} from './graph-context.mjs'
 import {createRgResolver} from '../mcp-rg.mjs'
 import {readSource, searchCode} from '../mcp-source-tools.mjs'
+import {extensionRuntimeSummary, normalizeWeavatrixExtensions} from './extension-api.mjs'
 
 const SELF_DIR = dirname(fileURLToPath(import.meta.url))
 const resolveRg = createRgResolver(SELF_DIR)
-// The default profile is fully offline and includes explicit local repository retargeting. Operators
-// who want a hard single-repository boundary can select the `pinned` profile instead. HTTP tools are
-// split into explicit `advisories` and `hosted` capabilities; the old `online` name remains an alias
-// for both so existing registrations keep working.
+// The core artifact has only local profiles. Online packages compose their own profiles through the
+// public extension API; the MIT package never contains a capability alias that can enable HTTP.
 export const DEFAULT_CAPS = Object.freeze(['graph', 'search', 'source', 'health', 'build', 'retarget', 'crossrepo'])
 const PROFILE_CAPS = Object.freeze({
     offline: DEFAULT_CAPS,
     pinned: ['graph', 'search', 'source', 'health', 'build'],
-    osv: [...DEFAULT_CAPS, 'advisories'],
-    hosted: [...DEFAULT_CAPS, 'advisories', 'hosted'],
-    full: [...DEFAULT_CAPS, 'advisories', 'hosted'],
 })
+const MOVED_PROFILES = new Set(['online', 'osv', 'hosted', 'full'])
 
 // The files whose mtime the stdio shell watches for hot reload — keep in sync with the imports in
 // loadHotApi below (catalog.mjs itself is last: a change here re-derives the whole table).
@@ -36,8 +33,7 @@ const HOT_OWNERS = [
     'graph/tools-core.mjs', 'graph/tools-query.mjs', 'tools-graph-hubs.mjs',
     'health/duplicates.mjs', 'health/dead-code.mjs', 'health/audit-format.mjs',
     'health/audit.mjs', 'health/structure.mjs', 'health/endpoints.mjs',
-    'actions/graph-lifecycle.mjs', 'actions/advisories.mjs',
-    'actions/hosted-architecture.mjs', 'actions/graph-sync.mjs',
+    'actions/graph-lifecycle.mjs',
     'architecture-starter.mjs', 'architecture-bootstrap.mjs',
     'company-contract-verdict.mjs',
 ]
@@ -76,13 +72,13 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
         {
             cap: 'crossrepo',
             name: 'trace_api_contract',
-            description: 'Cross-repository HTTP, GraphQL, gRPC and event/topic contract, handler-liveness and blast-radius evidence. Joins static backend contracts to registered client repositories; dynamic URLs/topics, reflection and unresolved runtime configuration remain explicit UNKNOWN evidence. Medium/high-confidence external matches mark a handler/contract NOT_DEAD_EXTERNAL_USE. Repository paths stay local and cannot be supplied through this tool.',
+            description: 'Cross-repository HTTP, GraphQL, gRPC and event/topic contract, handler-liveness and blast-radius evidence. Joins static models with optional revision-bound runtime/OTLP evidence; unobserved dynamic URLs/topics/reflection remain explicit UNKNOWN. Medium/high-confidence external matches mark a handler/contract NOT_DEAD_EXTERNAL_USE. Repository paths stay local and runtime report paths are repository-contained.',
             inputSchema: {
                 type: 'object',
                 properties: {
                     backend: {type: 'string', description: 'Backend repository UUID or exact unambiguous registry label'},
                     clients: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 20, description: 'Client repository UUIDs or exact unambiguous registry labels'},
-                    transport: {type: 'string', enum: ['all', 'http', 'graphql', 'grpc', 'event'], default: 'all', description: 'Contract family to trace; all runs every supported static detector'},
+                    transport: {type: 'string', enum: ['all', 'http', 'graphql', 'grpc', 'event'], default: 'all', description: 'Contract family to trace; all runs static and revision-bound runtime evidence for every supported transport'},
                     method: {type: 'string', enum: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']},
                     path: {type: 'string', maxLength: 2048, description: 'Optional full route or segment-aligned route fragment; /query matches /edgeAnalytics/query/... and {id}, :id and concrete parameter values are normalized'},
                     changed_files: {type: 'array', items: {type: 'string'}, maxItems: 500, description: 'Optional backend repo-relative changed files; only endpoints declared in those files are traced'},
@@ -107,6 +103,8 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
                     },
                     auto_discover_wrappers: {type: 'boolean', default: true, description: 'Discover only simple unambiguous functions that forward a URL parameter directly to a known object-style HTTP client'},
                     runtime_config: {type: 'object', maxProperties: 50, additionalProperties: {type: 'string', maxLength: 2048}, description: 'Optional non-secret static bindings for runtime URL prefixes, e.g. process.env.API_BASE. Values are used locally for this call and are not returned.'},
+                    runtime_evidence_files: {type: 'object', maxProperties: 21, additionalProperties: {type: 'string', maxLength: 512}, description: 'Optional repository-label/UUID to repository-relative weavatrix.transport-runtime.v1 JSON path. Defaults to .weavatrix/transport-runtime.json or .weavatrix/reports/transport-runtime.json in each repository.'},
+                    runtime_evidence_max_age_hours: {type: 'integer', minimum: 1, maximum: 8760, default: 168, description: 'Maximum accepted age for a revision-matched runtime evidence report'},
                     include_tests: {type: 'boolean', default: false},
                     max_impact_depth: {type: 'integer', minimum: 0, maximum: 5, default: 2},
                     max_endpoints: {type: 'integer', minimum: 1, maximum: 500, default: 250},
@@ -123,7 +121,7 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
           {cap: 'source', name: 'read_source', description: "Read the actual source of a node (by label/ID) or a repo-relative file path — the symbol's lines with context. The graph stores only locations, not source text. For a path read, pass start_line to anchor the window anywhere in the file (otherwise it shows the head).", inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'node label or ID'}, path: {type: 'string', description: 'or a repo-relative file path'}, start_line: {type: 'integer', description: 'anchor line: window = start_line-before .. start_line+after'}, before: {type: 'integer', default: 3}, after: {type: 'integer', default: 40}}}, run: (g, a, ctx) => readSource({repoRoot: ctx.repoRoot, resolveNode, isSymbol}, g, a)},
           {cap: 'source', refreshGraph: true, name: 'inspect_symbol', description: 'Inspect one exact symbol with an on-demand TypeScript/JavaScript LSP reference query, grouped occurrence containers, graph blast radius, complexity facts and bounded local source context. Ambiguous labels fail closed; point queries never replace the broad precision overlay.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_containers: {type: 'integer', minimum: 1, maximum: 50, default: 15}, context_lines: {type: 'integer', minimum: 0, maximum: 40, default: 8}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => ts.tInspectSymbol(g, a, ctx)},
           {cap: 'source', refreshGraph: true, name: 'context_bundle', description: 'Return one compact, bounded source bundle for an exact symbol: definition, production-first inbound/outbound containers, exact re-export sites, on-demand TS/JS reference evidence and diverse excerpts around call sites. Use before an edit when query_graph would be too broad.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Exact node ID or unambiguous symbol label'}, precision: {type: 'string', enum: ['auto', 'graph', 'lsp'], default: 'auto'}, max_references: {type: 'integer', minimum: 1, maximum: 5000, default: 1000}, max_related: {type: 'integer', minimum: 1, maximum: 30, default: 10}, max_reexports: {type: 'integer', minimum: 1, maximum: 100, default: 20}, max_source_files: {type: 'integer', minimum: 1, maximum: 8, default: 4}, context_lines: {type: 'integer', minimum: 0, maximum: 12, default: 4}, include_classified: {type: 'boolean', default: false, description: 'Include test/e2e/generated/mock/story/docs/benchmark/temp callers after production callers'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 60000, default: 30000}}, required: ['label']}, run: (g, a, ctx) => tb.tContextBundle(g, a, ctx, ts.tInspectSymbol)},
-        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Supports high-confidence small clones down to 12 tokens when min_tokens is lowered. Tests, classified non-product paths, and all-router framework boilerplate clone groups are excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', minimum: 12, maximum: 400, description: 'min fragment size, 12-400; default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_boilerplate: {type: 'boolean', default: false, description: 'Include clone groups made entirely of conventional *.router.js/ts router symbols'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
+        {cap: 'health', name: 'find_duplicates', description: "Content-based clone detection over production code (MOSS winnowing over method bodies). Supports high-confidence small clones down to 12 tokens when min_tokens is lowered. Tests, classified non-product paths, all-router framework boilerplate and immutable declarative catalogs are excluded by default; opt them in explicitly.", inputSchema: {type: 'object', properties: {min_similarity: {type: 'integer', description: '50-100, default 80 (ignored in semantic mode)'}, min_tokens: {type: 'integer', minimum: 12, maximum: 400, description: 'min fragment size, 12-400; default 50'}, mode: {type: 'string', enum: ['renamed', 'strict', 'semantic'], default: 'renamed'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, include_boilerplate: {type: 'boolean', default: false, description: 'Include clone groups made entirely of conventional *.router.js/ts router symbols'}, include_declarative: {type: 'boolean', default: false, description: 'Include repeated immutable array/object catalogs that contain no executable control flow'}, include_strings: {type: 'boolean', description: 'Also clone-check large multi-line string literals', default: false}, top_n: {type: 'integer', default: 15}}}, run: (g, a, ctx) => th.tFindDuplicates(g, a, ctx)},
         {cap: 'health', name: 'find_dead_code', description: 'Conservative review queue for statically unreferenced files, functions, methods and symbols. Returns confidence, reason, bounded evidence and explicit framework/dynamic/reflection/public-API caveats; never an auto-delete verdict. Tests, generated code, mocks, stories, docs, benchmarks and temporary roots are excluded by default.', inputSchema: {type: 'object', properties: {path: {type: 'string', maxLength: 1024, description: 'Optional repo-relative path prefix'}, kinds: {type: 'array', items: {type: 'string', enum: ['file', 'function', 'method', 'symbol']}, maxItems: 4, uniqueItems: true, description: 'Optional candidate kinds; defaults to all'}, min_confidence: {type: 'string', enum: ['high', 'medium', 'low'], default: 'medium', description: 'Minimum confidence to include. low explicitly includes public/framework/dynamic review candidates'}, include_tests: {type: 'boolean', default: false}, include_classified: {type: 'boolean', default: false, description: 'Include generated/mock/story/docs/benchmark/temp and paths explicitly classified as excluded; tests still require include_tests'}, top_n: {type: 'integer', minimum: 1, maximum: 100, default: 30}}}, run: (g, a, ctx) => th.tFindDeadCode(g, a, ctx)},
         {cap: 'health', name: 'run_audit', description: 'Core production-first repository Health review with an explicit capability/completeness matrix for structure, dependencies, bounded runtime-correctness/concurrency patterns, advisories, malware and coverage. Unsupported Maven/Gradle import verification is NOT_SUPPORTED/PARTIAL, never a clean zero. Findings whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded are suppressed by default; opt them in with include_classified. category=dependencies is a dedicated dependency-health projection across missing, unused and duplicate declarations while preserving each finding\'s native category. With base_ref, builds and audits an immutable Git checkout and compares stable deterministic finding IDs; debt defaults to genuinely new findings. Supply-chain checks remain explicitly uncomparable across the source-only baseline. changed_files without base_ref is only changed-scope, never a new-debt claim.', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['dependencies', 'unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category; dependencies selects dependency manifest/import findings across native categories'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_classified: {type: 'boolean', default: false, description: 'Include findings whose evidence is entirely tests/e2e/generated/mocks/stories/docs/benchmarks/temp or explicitly excluded'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}, base_ref: {type: 'string', maxLength: 200, description: 'Optional immutable Git baseline (for example HEAD~1 or origin/main). Enables honest new/existing/fixed debt comparison'}, changed_files: {type: 'array', items: {type: 'string'}, minItems: 1, maxItems: 500, description: 'Optional explicit repo-relative scope. Without base_ref this is changed-scope only; when omitted with base_ref, files are derived from the Git diff'}, debt: {type: 'string', enum: ['new', 'existing', 'all'], default: 'new', description: 'Baseline comparison view. Defaults to genuinely new deterministic findings when base_ref is present'}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
         {cap: 'health', name: 'coverage_map', description: 'Map a real existing coverage report onto the graph. If no report exists, return clearly labelled static test reachability (a test imports/reaches a source file) with actualCoverage=NOT_AVAILABLE; reachability is never presented as measured coverage.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
@@ -141,10 +139,6 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
         {cap: 'health', name: 'propose_architecture_exception', description: 'Prepare, but never apply, a bounded exception proposal for human review.', inputSchema: {type: 'object', properties: {fingerprint: {type: 'string'}, reason: {type: 'string'}, expires: {type: 'string', description: 'Optional YYYY-MM-DD'}}, required: ['fingerprint', 'reason']}, run: (g, a, ctx) => tar.tProposeArchitectureException(g, a, ctx)},
         {cap: 'retarget', name: 'open_repo', description: 'OFFLINE RETARGET: switch this server to another local Git repository, building its graph when missing. This explicit tool call changes the active repository boundary; pass build:false to probe without building. Omitted mode/precision preserve an existing graph; a new graph uses full and the startup precision setting (lsp unless WEAVATRIX_PRECISION=off). Omit the retarget capability at registration to pin one repository.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Absolute path to a Git working tree'}, build: {type: 'boolean', description: 'Build the graph when missing (default true)', default: true}, mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], description: 'Optional build mode override; omit to preserve an existing graph'}, precision: {type: 'string', enum: ['lsp', 'off'], description: 'Optional semantic precision override; omit to preserve an existing graph or use the startup setting for a new graph'}} , required: ['path']}, run: (g, a, ctx) => ta.tOpenRepo(g, a, ctx)},
         {cap: 'retarget', name: 'list_known_repos', description: 'OFFLINE RETARGET: list every registered local repository graph from the global per-user registry, regardless of parent folder.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tListKnownRepos(g, a, ctx)},
-        {cap: 'advisories', name: 'refresh_advisories', description: "NETWORK / explicit advisories profile: refresh the local OSV advisory store for this repo's concrete npm/PyPI/Go/Maven/Gradle/Cargo package versions. Sends package names + versions to OSV.dev — never automatic, never source code. Afterwards run_audit reads the refreshed store fully offline (~/.weavatrix/advisories.json).", inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', description: 'Per-request timeout, default 20000'}}}, run: (g, a, ctx) => ta.tRefreshAdvisories(g, a, ctx)},
-        {cap: 'hosted', name: 'pull_architecture_contract', description: 'NETWORK / explicit hosted profile: fetch the owner-approved target architecture for the active stable repository UUID, validate it and cache it locally. Sends only the opaque UUID with bearer auth; never source or paths. HTTP failures are returned as actionable AUTH_REQUIRED/FORBIDDEN/NOT_FOUND/REPOSITORY_NOT_READY states.', inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000}}}, run: (g, a, ctx) => ta.tPullArchitectureContract(g, a, ctx)},
-        {cap: 'hosted', name: 'preview_sync', description: 'LOCAL SAFETY PREVIEW / no network: serialize the exact bounded hosted payload, validate the HTTPS destination, and show hostname/path, repository UUID, fields, sections, node/edge counts, bytes and body hash. Returns a five-minute confirmation token for sync_graph. Source bodies, snippets, absolute paths, environment values, credentials, Git remotes and unknown fields are excluded.', inputSchema: {type: 'object', properties: {payload_version: {type: 'integer', enum: [2, 3], default: 3, description: '3 includes bounded architecture/health/stack/package evidence; 2 is explicit graph-only compatibility'}}}, run: (g, a, ctx) => ta.tPreviewSyncGraph(g, a, ctx)},
-        {cap: 'hosted', name: 'sync_graph', description: 'NETWORK / explicit hosted profile. Uploads only the exact payload created by preview_sync and requires dry_run:false plus its short-lived confirm_token after user approval. Calling without dry_run:false remains a no-network preview compatibility alias. Source bodies, snippets, absolute paths and unknown fields are never uploaded.', inputSchema: {type: 'object', properties: {payload_version: {type: 'integer', enum: [2, 3], default: 3, description: 'Used only when producing a compatibility preview; the approved token pins the exact serialized payload'}, dry_run: {type: 'boolean', default: true, description: 'Compatibility safety switch. Must be explicitly false to send.'}, confirm_token: {type: 'string', maxLength: 64, description: 'Short-lived token returned by preview_sync for the exact destination and payload'}, timeout_ms: {type: 'integer', minimum: 1000, maximum: 120000, default: 30000, description: 'Network timeout in milliseconds'}}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
     ]
     // Every tool supports the same machine-output switch. Text mode is TextContent-only so large
     // analysis payloads are not duplicated into an agent's context; JSON opts into structuredContent
@@ -170,7 +164,7 @@ function buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps}) {
 // Import the tool modules (cache-busted when version > 0), build the catalog, apply the caps filter.
 // capsArg semantics: undefined/null = offline defaults; a
 // present string (even '') is an explicit selection, so "select nothing" really exposes nothing.
-export async function loadHotApi(version, capsArg) {
+export async function loadHotApi(version, capsArg, {extensions: extensionDefinitions = []} = {}) {
     const v = version ? `?v=${version}` : ''
     const [tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv] = await Promise.all([
         import(new URL(`./tools-graph.mjs${v}`, import.meta.url).href),
@@ -185,18 +179,50 @@ export async function loadHotApi(version, capsArg) {
         import(new URL(`./tools-company.mjs${v}`, import.meta.url).href),
         import(new URL(`./tools-verified-change.mjs${v}`, import.meta.url).href),
     ])
+    const extensions = normalizeWeavatrixExtensions(extensionDefinitions)
+    const extensionProfiles = Object.assign({}, ...extensions.map((extension) => extension.profiles))
+    for (const name of Object.keys(extensionProfiles)) {
+        if (Object.hasOwn(PROFILE_CAPS, name)) throw new TypeError(`extension profile collides with core profile: ${name}`)
+    }
+    const profiles = {...PROFILE_CAPS, ...extensionProfiles}
     const raw = capsArg == null ? 'offline' : String(capsArg).trim()
-    const profile = Object.hasOwn(PROFILE_CAPS, raw) ? raw : 'custom'
-    const selected = PROFILE_CAPS[raw] || raw.split(',').map((s) => s.trim()).filter(Boolean)
-        .flatMap((cap) => cap === 'online' ? ['advisories', 'hosted'] : [cap])
+    if (MOVED_PROFILES.has(raw) && !Object.hasOwn(extensionProfiles, raw)) {
+        throw new Error(`MCP profile "${raw}" moved to weavatrix-online; the MIT core exposes only offline network-free profiles`)
+    }
+    const profile = Object.hasOwn(profiles, raw) ? raw : 'custom'
+    const selected = profiles[raw] || raw.split(',').map((s) => s.trim()).filter(Boolean)
     const caps = new Set(selected)
-    const all = buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps})
+    const coreTools = buildTools({tg, ti, th, ts, tb, te, ta, tar, thi, tc, tv, caps})
+    const extensionTools = extensions.flatMap((extension) => extension.tools.map((tool) => ({...tool, extension: extension.name})))
+    const all = [...coreTools, ...extensionTools.map((tool) => ({
+        ...tool,
+        inputSchema: {
+            ...(tool.inputSchema || {type: 'object'}),
+            properties: {
+                ...(tool.inputSchema?.properties || {}),
+                output_format: {
+                    type: 'string', enum: ['text', 'json'], default: 'text',
+                    description: 'text returns concise TextContent; json also returns the stable structuredContent envelope',
+                },
+            },
+        },
+    }))]
+    const toolNames = new Set()
+    for (const tool of all) {
+        if (toolNames.has(tool.name)) throw new TypeError(`extension tool collides with an existing tool: ${tool.name}`)
+        toolNames.add(tool.name)
+    }
     const tools = all.filter((t) => caps.has(t.cap))
     return {
         tools,
         byName: new Map(tools.map((t) => [t.name, t])),
         caps,
         profile,
+        extensions: {
+            items: extensionRuntimeSummary(extensions),
+            auditProviders: extensions.flatMap((extension) => extension.auditProviders.map((provider) => ({...provider, extension: extension.name}))),
+            skills: extensions.flatMap((extension) => extension.skills.map((skill) => ({...skill, extension: extension.name}))),
+        },
         stalenessLine,
         resetStalenessCache,
     }

package/src/mcp/evidence/duplicate-member-order.mjs

@@ -1,6 +1,6 @@
 const compareText = (left, right) => String(left).localeCompare(String(right), 'en')
 
-// Snapshot construction and hosted-payload validation must use the same stable
+// Snapshot construction and source-free payload validation must use the same stable
 // member order or equivalent evidence can hash differently across the boundary.
 export function compareDuplicateMember(left, right) {
     return compareText(left.file, right.file) || left.startLine - right.startLine ||

package/src/mcp/evidence-snapshot.health.mjs

@@ -54,9 +54,9 @@ export function buildHealthSection(graph, audit, repoRoot = null) {
             complexity: {thresholds: COMPLEXITY_THRESHOLDS, analyzed: 0, hotspots: []},
         }
     }
-    // Public/private hosted evidence follows the same production-first path policy as
+    // Source-free extension evidence follows the same production-first path policy as
     // run_audit. Classified-only findings remain available locally through
-    // include_classified:true, but must not turn a hosted production snapshot red.
+    // include_classified:true, but must not turn a production snapshot red.
     const scopedFindings = auditFindingPathScope(audit.findings, {repoRoot}).findings
     const scopedSummary = summarizeFindings(scopedFindings)
     const findings = bounded(scopedFindings.map(sanitizeFinding).filter(Boolean)

package/src/mcp/extension-api.mjs

@@ -0,0 +1,77 @@
+const EXTENSION_NAME = /^[a-z0-9][a-z0-9._-]{0,127}$/
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,127}$/
+
+const asArray = (value, field) => {
+    if (value == null) return []
+    if (!Array.isArray(value)) throw new TypeError(`${field} must be an array`)
+    return value
+}
+
+const validateProfiles = (profiles = {}) => {
+    if (!profiles || typeof profiles !== 'object' || Array.isArray(profiles)) throw new TypeError('extension profiles must be an object')
+    const normalized = {}
+    for (const [name, capabilities] of Object.entries(profiles)) {
+        if (!EXTENSION_NAME.test(name)) throw new TypeError(`invalid extension profile name: ${name}`)
+        normalized[name] = asArray(capabilities, `profile ${name}`).map(String)
+    }
+    return Object.freeze(normalized)
+}
+
+const validateTools = (tools = []) => Object.freeze(asArray(tools, 'extension tools').map((tool) => {
+    if (!tool || typeof tool !== 'object') throw new TypeError('each extension tool must be an object')
+    if (!TOOL_NAME.test(String(tool.name || ''))) throw new TypeError(`invalid extension tool name: ${tool.name || '(missing)'}`)
+    if (!EXTENSION_NAME.test(String(tool.cap || ''))) throw new TypeError(`invalid extension tool capability: ${tool.cap || '(missing)'}`)
+    if (typeof tool.run !== 'function') throw new TypeError(`extension tool ${tool.name} must provide run()`)
+    return Object.freeze({...tool})
+}))
+
+const validateAuditProviders = (providers = []) => Object.freeze(asArray(providers, 'auditProviders').map((provider) => {
+    if (!provider || typeof provider !== 'object') throw new TypeError('each audit provider must be an object')
+    if (!EXTENSION_NAME.test(String(provider.id || ''))) throw new TypeError(`invalid audit provider id: ${provider.id || '(missing)'}`)
+    if (typeof provider.run !== 'function') throw new TypeError(`audit provider ${provider.id} must provide run()`)
+    if (provider.network !== undefined && provider.network !== 'none') throw new TypeError(`audit provider ${provider.id} must be local (network: "none")`)
+    return Object.freeze({...provider, network: 'none'})
+}))
+
+const validateSkills = (skills = []) => Object.freeze(asArray(skills, 'skills').map((skill) => {
+    if (!skill || typeof skill !== 'object') throw new TypeError('each extension skill must be an object')
+    if (!EXTENSION_NAME.test(String(skill.name || ''))) throw new TypeError(`invalid extension skill name: ${skill.name || '(missing)'}`)
+    if (!String(skill.path || '').trim()) throw new TypeError(`extension skill ${skill.name} must provide a package-relative path`)
+    return Object.freeze({...skill, name: String(skill.name), path: String(skill.path)})
+}))
+
+// Public composition contract for packages layered on top of the MIT core. Extensions may add
+// tools, local audit providers and packaged skills, but cannot replace core tools or profiles.
+export function defineWeavatrixExtension(spec) {
+    if (!spec || typeof spec !== 'object') throw new TypeError('extension definition must be an object')
+    const name = String(spec.name || '')
+    const version = String(spec.version || '')
+    if (!EXTENSION_NAME.test(name)) throw new TypeError(`invalid extension name: ${name || '(missing)'}`)
+    if (!version.trim()) throw new TypeError(`extension ${name} must provide a version`)
+    return Object.freeze({
+        name,
+        version,
+        tools: validateTools(spec.tools),
+        profiles: validateProfiles(spec.profiles),
+        auditProviders: validateAuditProviders(spec.auditProviders),
+        skills: validateSkills(spec.skills),
+    })
+}
+
+export function normalizeWeavatrixExtensions(extensions = []) {
+    const normalized = asArray(extensions, 'extensions').map((extension) => defineWeavatrixExtension(extension))
+    const names = new Set()
+    for (const extension of normalized) {
+        if (names.has(extension.name)) throw new TypeError(`duplicate extension name: ${extension.name}`)
+        names.add(extension.name)
+    }
+    return Object.freeze(normalized)
+}
+
+export const extensionRuntimeSummary = (extensions = []) => extensions.map((extension) => ({
+    name: extension.name,
+    version: extension.version,
+    tools: extension.tools.length,
+    auditProviders: extension.auditProviders.length,
+    skills: extension.skills.map((skill) => skill.name),
+}))

package/src/mcp/health/audit-format.mjs

@@ -52,7 +52,7 @@ export const auditFilter = (audit, args, findings = audit.findings, repoRoot = n
 
 const auditChecksLine = (audit) => {
     const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
-    return `Checks: ${check('OSV', audit.checks?.osv)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`
+    return `Checks: ${check('OSV', audit.checks?.osv)}; ${check('RustSec report', audit.checks?.rustsec)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`
 }
 
 const auditCapabilityLines = (audit) => {
@@ -74,6 +74,15 @@ const auditCapabilityLines = (audit) => {
     return lines
 }
 
+const auditExtensionLines = (audit) => {
+    const items = audit.extensionCapabilities || []
+    if (!items.length) return []
+    return [
+        'Extension analyzer matrix (status/completeness):',
+        ...items.map((item) => `  ${item.extension ? `${item.extension}/` : ''}${item.id}: ${item.status}/${item.completeness} — ${item.detail} (${item.findingCount} finding(s)).`),
+    ]
+}
+
 const auditDependencyCoverageLines = (deps) => {
     const ecosystems = Object.values(deps.ecosystems || {}).filter((item) => item?.present)
     const verification = Object.entries(deps.verificationCoverage || {})
@@ -138,6 +147,7 @@ export const formatOrdinaryAudit = (audit, args, findings = audit.findings, head
         auditDependencySummaryLine(audit, deps),
         ...auditDependencyCoverageLines(deps),
         ...auditCapabilityLines(audit),
+        ...auditExtensionLines(audit),
         `Scoped severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Scoped categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         pathScope.suppressed ? `Path policy: production-first; suppressed ${pathScope.suppressed} finding(s) whose evidence is entirely test/e2e/generated/mock/story/docs/benchmark/temp or explicitly excluded. Pass include_classified:true to include them.` : 'Path policy: production-first; no classified-only findings were suppressed.',
         `Repository-level ${auditChecksLine(audit)}`,

package/src/mcp/health/audit.mjs

@@ -1,5 +1,6 @@
 import {rawGraph, effectiveRawGraph} from '../graph-context.mjs'
 import {runInternalAudit} from '../../analysis/internal-audit.js'
+import {applyAuditExtensions} from '../../analysis/audit-extensions.js'
 import {classifyChangeImpact} from '../../analysis/change-classification.js'
 import {
   compareAuditDebt,
@@ -19,6 +20,11 @@ const {
   pathsFromClassification,
 } = await import(new URL(`./audit-format.mjs${auditFormatVersion}`, import.meta.url).href)
 
+const runAudit = async (repoRoot, graph, args, ctx, options = {}) => applyAuditExtensions(
+    await runInternalAudit(repoRoot, {graph, ...options}),
+    {providers: ctx.extensions?.auditProviders || [], repoRoot, graph, args},
+)
+
 async function runAuditWithBaseline(args, ctx, currentGraph) {
     const resolved = resolveGitCommit(ctx.repoRoot, args.base_ref)
     if (!resolved.ok) return toolResult(`Audit baseline unavailable: ${resolved.error}.`, {
@@ -27,10 +33,7 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
 
     let currentAudit
     try {
-        currentAudit = await runInternalAudit(ctx.repoRoot, {
-            graph: currentGraph,
-            skipMalwareScan: !args.include_malware_scan,
-        })
+        currentAudit = await runAudit(ctx.repoRoot, currentGraph, args, ctx, {skipMalwareScan: !args.include_malware_scan})
     } catch (error) {
         const reason = error instanceof Error ? error.message : String(error)
         return toolResult(`Audit failed while building the current graph: ${reason}`, {
@@ -86,7 +89,7 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
         if (currentMode !== 'full') graph = filterGraphForMode(graph, currentMode, {repoRoot: checkout})
         graph.graphBuildMode = currentMode
         graph.graphBuildScope = ''
-        return runInternalAudit(checkout, {graph, skipMalwareScan: true})
+        return runAudit(checkout, graph, args, ctx, {skipMalwareScan: true})
     })
     if (!baseline.ok || !baseline.value?.ok) {
         const reason = baseline.error || baseline.value?.error || 'baseline audit failed'
@@ -146,8 +149,8 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
 export async function tRunAudit(g, args, ctx) {
     if (!ctx.repoRoot) return 'Audit needs the repo root (not provided to this server).'
     if (args.base_ref) return runAuditWithBaseline(args, ctx, rawGraph(ctx))
-    const audit = await runInternalAudit(ctx.repoRoot, {
-        graph: effectiveRawGraph(ctx),
+    const graph = effectiveRawGraph(ctx)
+    const audit = await runAudit(ctx.repoRoot, graph, args, ctx, {
         skipMalwareScan: !args.include_malware_scan, // greps installed packages — slow, so opt-in
     })
     if (!audit.ok) return `Audit failed: ${audit.error}`

package/src/mcp/health/duplicates.mjs

@@ -66,7 +66,10 @@ export function tFindDuplicates(g, args, ctx) {
     const boilerplateNote = analysis.boilerplateSuppressed
         ? ` ${analysis.boilerplateSuppressed} all-router framework boilerplate group(s) were suppressed; pass include_boilerplate:true to inspect them.`
         : ''
-    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}${boilerplateNote}`
+    const declarativeNote = analysis.declarativeSuppressed
+        ? ` ${analysis.declarativeSuppressed} immutable declarative catalog group(s) were suppressed; pass include_declarative:true to inspect repeated data shapes.`
+        : ''
+    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}${boilerplateNote}${declarativeNote}`
     const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
     const lines = top.map((grp, k) => {
         const isStr = grp.members.some((f) => f.kind === 'string')
@@ -74,10 +77,9 @@ export function tFindDuplicates(g, args, ctx) {
         const sites = grp.members.slice(0, 8).map((f) => `     ${f.file}:${f.start}-${f.end}`)
         return [head, ...sites].join('\n')
     })
-    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}${boilerplateNote}`
+    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}${boilerplateNote}${declarativeNote}`
 }
 
 // Focused dead-code review queue. Unlike the broad run_audit surface, this includes functions and
 // methods with bounded source-free evidence, and explicitly demotes framework/dynamic/public API
 // candidates. It never returns an automatic-delete verdict.
-

package/src/mcp/sync-payload.mjs

@@ -1,4 +1,4 @@
-// Versioned, explicit wire schema for sync_graph. Never forward graph.json wholesale.
+// Versioned, explicit source-free extension schema. Never forward graph.json wholesale.
 import {sanitizeEvidenceSnapshot} from './sync-evidence.mjs';
 import {
     MAX_SYNC_EXTERNAL_IMPORTS, MAX_SYNC_LINKS, MAX_SYNC_NODES, assertArrayLimit,

package/src/mcp/tools-actions.mjs

@@ -2,17 +2,10 @@
 // behaviorally identical to the former single-file implementation.
 const version = new URL(import.meta.url).search
 const load = (path) => import(new URL(`${path}${version}`, import.meta.url).href)
-const [lifecycle, advisories, architecture, sync] = await Promise.all([
+const [lifecycle] = await Promise.all([
   load('./actions/graph-lifecycle.mjs'),
-  load('./actions/advisories.mjs'),
-  load('./actions/hosted-architecture.mjs'),
-  load('./actions/graph-sync.mjs'),
 ])
 
 export const tOpenRepo = lifecycle.tOpenRepo
 export const tListKnownRepos = lifecycle.tListKnownRepos
 export const tRebuildGraph = lifecycle.tRebuildGraph
-export const tRefreshAdvisories = advisories.tRefreshAdvisories
-export const tPullArchitectureContract = architecture.tPullArchitectureContract
-export const tPreviewSyncGraph = sync.tPreviewSyncGraph
-export const tSyncGraph = sync.tSyncGraph

package/src/mcp/tools-architecture.mjs

@@ -17,7 +17,7 @@ const activeContract = bootstrap.activeArchitectureContract
 
 const remediation = () => ({
     offlinePath: '.weavatrix/architecture.json',
-    hostedAction: 'Open Architecture -> choose intended style -> Save target & baseline',
+    extensionAction: 'A composing extension may provide owner-approved remote contract storage',
     nextTool: 'verify_architecture',
 })
 
@@ -38,7 +38,7 @@ function notConfiguredResult(g, action, {includeStarter = false, repoRoot = null
         : ''
     return toolResult([
         `Architecture ${action} is NOT_CONFIGURED — no target contract is active.${starterText}`,
-        'Next: save .weavatrix/architecture.json (offline) or approve a target in Hosted, then call verify_architecture.',
+        'Next: save .weavatrix/architecture.json, then call verify_architecture.',
     ].join('\n'), {
         state: 'NOT_CONFIGURED',
         remediation: remediation(),

package/src/mcp/tools-company.mjs

@@ -193,7 +193,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
             totals: {...analysis.totals, endpoints: 0, clientCalls: 0, matches: 0, methodMismatches: 0, uncertainCalls: 0, notDeadExternalUse: 0, notDeadExternalHandlers: 0, possibleExternalUse: 0, unknownLiveness: 0},
         }
         const transportAnalysis = selectedTransport === 'http'
-            ? {transportContractsV: 1, transport: 'http', status: 'COMPLETE', completeness: {complete: true, reasons: []}, totals: {contracts: 0, matches: 0, uncertain: 0, filesScanned: 0}, contracts: [], uncertain: []}
+            ? {transportContractsV: 2, transport: 'http', status: 'COMPLETE', completeness: {complete: true, reasons: []}, totals: {contracts: 0, matches: 0, uncertain: 0, filesScanned: 0, runtimeObservations: 0, runtimeResolved: 0, runtimeReportsComplete: 0}, contracts: [], uncertain: [], runtimeEvidence: {status: 'NOT_APPLICABLE', reports: [], resolvedUnknowns: 0}}
             : analyzeTransportContracts({
                 backend: {id: backendAlias, repoRoot: backend.repoPath, graph: backendGraph.graph},
                 clients: clientGraphs.map((item) => ({id: item.alias, repoRoot: item.record.repoPath, graph: item.graph})),
@@ -201,6 +201,8 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
                 includeTests: args.include_tests === true,
                 maxImpactDepth: args.max_impact_depth,
                 maxAffectedFiles: args.max_affected_files,
+                runtimeEvidenceFiles: args.runtime_evidence_files,
+                runtimeEvidenceMaxAgeHours: args.runtime_evidence_max_age_hours,
             })
         const verdict = contractVerdict(analysis, transportAnalysis)
         const reasons = [...new Set([...reconciliationReasons, ...(analysis.completeness?.reasons || []), ...(transportAnalysis.completeness?.reasons || [])])]
@@ -232,7 +234,7 @@ export async function tTraceApiContract(_g, args = {}, ctx = {}) {
             ...transportAnalysis.contracts.filter((contract) => contract.callsites.length).slice(0, topN).map((contract) =>
                 `  ${contract.transport.toUpperCase()} ${contract.service ? `${contract.service}.` : contract.operation ? `${contract.operation} ` : ''}${contract.name} (${contract.file}:${contract.line}) [${contract.liveness}] → ${contract.callsites.length} callsite(s), ${contract.affected.files.length} affected file(s)`),
             completeness.complete
-                ? 'Completeness: complete within the declared repository graphs and supported static HTTP/GraphQL/gRPC/event models.'
+                ? 'Completeness: complete within the declared repository graphs, supported static models and fresh revision-bound runtime capture.'
                 : `Completeness: partial — ${completeness.reasons.join('; ')}.`,
         ]
         const result = {

package/src/mcp-runtime.mjs

@@ -0,0 +1,2 @@
+export {startMcpServer} from './mcp-server.mjs'
+export {DEFAULT_CAPS} from './mcp/catalog.mjs'

package/src/mcp-server.mjs

@@ -1,9 +1,4 @@
-// weavatrix MCP server — the stdio entry point. The tool implementations live in src/mcp/*:
-//   graph-context.mjs  — graph load + indexes, node resolution, staleness, raw-graph cache, diffs
-//   tools-graph.mjs    — graph query tools        tools-impact.mjs  — dependents / diff / change impact
-//   tools-health.mjs   — audit / clones / coverage / endpoints
-//   tools-actions.mjs  — rebuild / open_repo / list_known_repos + the 'online' group
-//   catalog.mjs        — tool catalog, capability filter, hot-reload loader
+// Weavatrix MCP stdio entry point; implementations and extension composition live in src/mcp/*.
 // Spawned by Claude Code / Codex as a plain Node child (node mcp-server.mjs <graph.json> <repoRoot>).
 // Speaks newline-delimited JSON-RPC 2.0 over stdio (the MCP stdio transport).
 //
@@ -17,6 +12,8 @@
 //   weavatrix-mcp <repoRoot> [caps]               — graph path derived from the standard layout
 //   weavatrix-mcp <graph.json> <repoRoot> [caps]  — explicit graph file (classic form)
 import process from 'node:process'
+import {resolve} from 'node:path'
+import {pathToFileURL} from 'node:url'
 import {loadGraph} from './mcp/graph-context.mjs'
 import {createStalenessNoticeGate} from './mcp/staleness-notice.mjs'
 import {normalizeToolResult} from './mcp/tool-result.mjs'
@@ -32,23 +29,33 @@ import {
 const DEFAULT_PROTOCOL = '2024-11-05'
 const log = (...a) => process.stderr.write(`[weavatrix] ${a.join(' ')}\n`)
 
-const target = resolveServerTarget(process.argv, log)
-const GRAPH_PATH = target.graphPath, REPO_ROOT = target.repoRoot, CAPS_ARG = target.capabilities
-
 // ---- hot reload of tool implementations -----------------------------------------------------------
 // Node caches modules at spawn, so edits to the tool code would otherwise be invisible until the MCP
 // client reconnects. Before each tools/list|call we stat the hot-reloadable files (HOT_FILES); when
 // any changed on disk we re-import them through catalog.loadHotApi with a cache-busting version and
 // swap the tool table, then notify the client. The stdio shell, graph-context (its caches), and the
 // analysis engines are NOT swapped — changing those still needs a reconnect.
-async function main() {
+export async function startMcpServer({
+    argv = process.argv,
+    defaultCapabilities,
+    loadExtensions = async () => [],
+    packageJsonPath = PACKAGE_JSON_PATH,
+    packageVersion = PKG_VERSION,
+    serverInfo = SERVER_INFO,
+} = {}) {
+    const target = resolveServerTarget(argv, log)
+    const GRAPH_PATH = target.graphPath
+    const REPO_ROOT = target.repoRoot
+    const CAPS_ARG = target.capabilities ?? defaultCapabilities
     let catalog = await loadCatalog()
-    let api = await catalog.loadHotApi(0, CAPS_ARG)
+    let extensions = await loadExtensions({version: 0})
+    let api = await catalog.loadHotApi(0, CAPS_ARG, {extensions})
     const runtimeInfo = () => ({
-        ...runtimeVersionStatus({runningVersion: PKG_VERSION, packageJsonPath: PACKAGE_JSON_PATH}),
+        ...runtimeVersionStatus({runningVersion: packageVersion, packageJsonPath}),
         profile: api.profile || 'custom',
         capabilities: [...api.caps],
         toolCount: api.tools.length,
+        ...(api.extensions.items.length ? {extensions: api.extensions.items} : {}),
     })
     const runtimeInstructions = () => {
         const runtime = runtimeInfo()
@@ -61,7 +68,7 @@ async function main() {
     let graphError = null
     // ctx owns the CURRENT target: rebuild_graph reloads it, open_repo retargets graphPath/repoRoot
     // at runtime. loadInto always reads ctx.graphPath so both paths share one loader.
-    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null, runtime: runtimeInfo()}
+    const ctx = {graphPath: GRAPH_PATH, repoRoot: REPO_ROOT, reload: null, runtime: runtimeInfo(), extensions: api.extensions}
     const loadInto = () => { graph = loadGraph(ctx.graphPath, {repoRoot: ctx.repoRoot}); graphError = null; return graph }
     ctx.reload = () => { api.resetStalenessCache(); try { return loadInto() } catch (e) { graphError = e.message; return null } }
     try {
@@ -114,10 +121,13 @@ async function main() {
         if (v <= loadedVersion || v === lastFailedVersion) return
         try {
             const nextCatalog = await loadCatalog(v)
-            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG)
+            const nextExtensions = await loadExtensions({version: v})
+            const nextApi = await nextCatalog.loadHotApi(v, CAPS_ARG, {extensions: nextExtensions})
             catalog = nextCatalog
             api = nextApi
+            extensions = nextExtensions
             ctx.runtime = runtimeInfo()
+            ctx.extensions = api.extensions
             loadedVersion = v
             log(`hot-reloaded tool implementations from changed source (${api.tools.length} tools)`)
             send({jsonrpc: '2.0', method: 'notifications/tools/list_changed'})
@@ -145,7 +155,7 @@ async function main() {
         if (method === 'initialize') {
             if (params?.protocolVersion) protocolVersion = String(params.protocolVersion)
             return reply(id, {
-                protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo: SERVER_INFO,
+                protocolVersion, capabilities: {tools: {listChanged: true}}, serverInfo,
                 instructions: runtimeInstructions(), _meta: {'weavatrix/runtime': runtimeInfo()},
             })
         }
@@ -281,7 +291,8 @@ async function main() {
 
 // Guard: hot-reload re-imports of tool modules never touch this entry, but keep the start guard so a
 // stray re-import of the entry itself can never spawn a second stdio loop.
-if (!globalThis.__weavatrixMcpStarted) {
+const directEntry = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+if (directEntry && !globalThis.__weavatrixMcpStarted) {
     globalThis.__weavatrixMcpStarted = true
-    main()
+    startMcpServer()
 }