contradiction-mcp 0.3.2 → 0.3.4

package/dist/server.js

@@ -16,7 +16,7 @@ function checkScope(scope, options) {
 }
 export function createMcpServer(options) {
     const name = options.name || 'contradiction-mcp';
-    const version = options.version || '0.3.1';
+    const version = options.version || '0.3.4';
     const reviewService = options.reviewService ?? (options.dbManager ? new ReviewService(options.dbManager) : undefined);
     const resolutionAdvisor = options.resolutionAdvisor ?? new ResolutionAdvisor();
     const metricsService = options.metricsService ?? globalMetrics;
@@ -33,13 +33,38 @@ export function createMcpServer(options) {
     });
     const registerTool = (toolName, description, schema, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    handler) => {
-        if (!schema || Object.keys(schema).length === 0) {
-            server.registerTool(toolName, { description }, handler);
+    handler, annotations, outputSchema) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const toolConfig = { description };
+        if (schema && Object.keys(schema).length > 0) {
+            toolConfig.inputSchema = schema;
         }
-        else {
-            server.registerTool(toolName, { description, inputSchema: schema }, handler);
+        if (annotations) {
+            toolConfig.annotations = annotations;
         }
+        if (outputSchema) {
+            toolConfig.outputSchema = outputSchema;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const wrappedHandler = async (args) => {
+            const res = await handler(args);
+            if (outputSchema && res && !res.isError && res.structuredContent === undefined) {
+                if (Array.isArray(res.content) && res.content[0]?.text) {
+                    try {
+                        res.structuredContent = JSON.parse(res.content[0].text);
+                    }
+                    catch {
+                        res.structuredContent = {};
+                    }
+                }
+                else {
+                    res.structuredContent = {};
+                }
+            }
+            return res;
+        };
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        server.registerTool(toolName, toolConfig, wrappedHandler);
     };
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     server.tool = registerTool;
@@ -47,7 +72,7 @@ export function createMcpServer(options) {
     // CANONICAL TOOLSET (12 VERB_NOUN TOOLS)
     // ==========================================
     // 1. Tool: check_health
-    registerTool('check_health', 'Checks the operational status of the Contradiction MCP server, including SQLite database connectivity, storage metrics, active connectors, and runtime diagnostics. Read-only and safe to invoke frequently for readiness and liveness probing.', {
+    registerTool('contradiction.health.check', 'Checks the operational status of the Contradiction MCP server, including SQLite database connectivity, storage metrics, active connectors, and runtime diagnostics. Read-only and safe to invoke frequently for readiness and liveness probing.', {
         verbose: z
             .boolean()
             .optional()
@@ -83,9 +108,36 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        status: z
+            .string()
+            .optional()
+            .describe('Overall server operational health status (healthy, degraded, unhealthy)'),
+        server: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Server metadata, version, and uptime'),
+        mcp: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('MCP protocol implementation details'),
+        database: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('SQLite storage and table status'),
+        timestamp: z.string().optional().describe('ISO-8601 status check timestamp'),
+        metrics: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Operational snapshot metrics'),
     });
     // 2. Tool: list_sources
-    registerTool('list_sources', 'Lists all registered external data source connectors (document, website, github) and ingested source entities tracked by the system, including source IDs, synchronization timestamps, and claim counts. Read-only operation. Use this tool to inspect available data sources before initiating scans or synchronization.', {
+    registerTool('contradiction.sources.list', 'Lists all registered external data source connectors (document, website, github) and ingested source entities tracked by the system, including source IDs, synchronization timestamps, and claim counts. Read-only operation. Use this tool to inspect available data sources before initiating scans or synchronization.', {
         type: z
             .enum(['document', 'website', 'github'])
             .optional()
@@ -136,9 +188,25 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        count: z.number().optional().describe('Number of registered connector instances'),
+        connectors: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Registered connector configurations'),
+        sourcesCount: z.number().optional().describe('Number of ingested source records returned'),
+        sources: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Ingested source entity records'),
     });
     // 3. Tool: test_connection
-    registerTool('test_connection', 'Validates connectivity, authentication, and accessibility for an external data source or connector (such as a GitHub repository, web URL, or local file) without persisting any data or modifying state. Use this tool to verify credentials and target reachability prior to running synchronization.', {
+    registerTool('contradiction.sources.test', 'Validates connectivity, authentication, and accessibility for an external data source or connector (such as a GitHub repository, web URL, or local file) without persisting any data or modifying state. Use this tool to verify credentials and target reachability prior to running synchronization.', {
         connector: z
             .enum(['github', 'website', 'document'])
             .describe('The connector type to validate (github, website, document)'),
@@ -217,9 +285,19 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, {
+        connector: z.string().optional().describe('Connector type tested'),
+        target: z.string().optional().describe('Target identifier validated'),
+        accessible: z.boolean().optional().describe('Whether target was accessible'),
+        message: z.string().optional().describe('Diagnostic connection message'),
     });
     // 4. Tool: sync_source
-    registerTool('sync_source', 'Ingests and synchronizes one or more external data sources (local document file, public website URL, or GitHub repository), extracts factual claims with exact line provenance, idempotently updates SQLite storage, and triggers automatic contradiction discovery. Mutating and idempotent operation. Supports single source ingestion or concurrent batch synchronization.', {
+    registerTool('contradiction.sources.sync', 'Ingests and synchronizes one or more external data sources (local document file, public website URL, or GitHub repository), extracts factual claims with exact line provenance, idempotently updates SQLite storage, and triggers automatic contradiction discovery. Mutating and idempotent operation. Supports single source ingestion or concurrent batch synchronization.', {
         connector: z
             .string()
             .describe('The external source connector to synchronize (document for local files, website for URLs, github for repositories)'),
@@ -346,9 +424,21 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    }, {
+        status: z.string().optional().describe('Status of synchronization'),
+        connector: z.string().optional().describe('Connector used for sync'),
+        repository: z.string().optional().describe('Source name or repository synced'),
+        claimsCreated: z.number().optional().describe('Number of new claims created'),
+        claimsUpdated: z.number().optional().describe('Number of existing claims updated'),
+        durationMs: z.number().optional().describe('Sync execution duration in milliseconds'),
     });
     // 5. Tool: scan_contradictions
-    registerTool('scan_contradictions', 'Discovers conflicting and inconsistent factual assertions across connected sources. Can scan the entire database, or scope the scan to a specific source, file, or single claim. Uses deterministic candidate grouping, entity resolution, and value comparison algorithms to detect and persist contradictions without duplicates. Mutating and idempotent.', {
+    registerTool('contradiction.conflicts.scan', 'Discovers conflicting and inconsistent factual assertions across connected sources. Can scan the entire database, or scope the scan to a specific source, file, or single claim. Uses deterministic candidate grouping, entity resolution, and value comparison algorithms to detect and persist contradictions without duplicates. Mutating and idempotent.', {
         sourceId: z
             .string()
             .optional()
@@ -417,9 +507,24 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        count: z.number().optional().describe('Total number of contradictions detected'),
+        contradictions: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Detected contradiction records'),
+        scannedCount: z
+            .number()
+            .optional()
+            .describe('Total number of claim candidate pairs evaluated'),
     });
     // 6. Tool: analyze_claim_pair
-    registerTool('analyze_claim_pair', 'Performs deep comparative analysis between two factual claims to determine whether they contradict each other. Evaluates semantic meaning, value differences, numeric/temporal ranges, and contextual dimensions (environment divergence, scope, source roles). Returns contradiction classification, severity, confidence score, and detailed explanation. Read-only operation.', {
+    registerTool('contradiction.claims.analyze', 'Performs deep comparative analysis between two factual claims to determine whether they contradict each other. Evaluates semantic meaning, value differences, numeric/temporal ranges, and contextual dimensions (environment divergence, scope, source roles). Returns contradiction classification, severity, confidence score, and detailed explanation. Read-only operation.', {
         claimAId: z.string().min(1).describe('The unique ID of the first claim'),
         claimBId: z.string().min(1).describe('The unique ID of the second claim'),
         explainContext: z
@@ -469,9 +574,30 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        hasContradiction: z
+            .boolean()
+            .optional()
+            .describe('Whether a factual conflict was detected between the claims'),
+        severity: z
+            .string()
+            .nullable()
+            .optional()
+            .describe('Contradiction severity: LOW, MEDIUM, HIGH, CRITICAL'),
+        confidence: z.number().optional().describe('Confidence score between 0.0 and 1.0'),
+        explanation: z
+            .string()
+            .optional()
+            .describe('Detailed explanation of contradiction rationale'),
+        suggestedAction: z.string().nullable().optional().describe('Recommended resolution action'),
     });
     // 7. Tool: list_claims
-    registerTool('list_claims', 'Queries stored factual assertions and claims extracted from connected sources with flexible filtering by subject, predicate, source, environment, and value type. Read-only operation. Use this tool to explore known facts, find subjects with multiple assertions, or inspect extracted data.', {
+    registerTool('contradiction.claims.list', 'Queries stored factual assertions and claims extracted from connected sources with flexible filtering by subject, predicate, source, environment, and value type. Read-only operation. Use this tool to explore known facts, find subjects with multiple assertions, or inspect extracted data.', {
         subject: z
             .string()
             .optional()
@@ -534,9 +660,21 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        count: z.number().optional().describe('Number of claims returned in current page'),
+        total: z.number().optional().describe('Total count of claims matching filters'),
+        claims: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('List of retrieved factual claims'),
     });
     // 8. Tool: get_claim
-    registerTool('get_claim', 'Retrieves complete details for a single factual claim by ID, including its subject, predicate, current and normalized values, provenance evidence, originating source metadata, and chronological historical value transitions over time. Read-only operation.', {
+    registerTool('contradiction.claims.get', 'Retrieves complete details for a single factual claim by ID, including its subject, predicate, current and normalized values, provenance evidence, originating source metadata, and chronological historical value transitions over time. Read-only operation.', {
         claimId: z.string().min(1).describe('The unique ID of the claim to retrieve'),
         includeHistory: z
             .boolean()
@@ -577,9 +715,24 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        claim: z
+            .record(z.string(), z.unknown())
+            .nullable()
+            .optional()
+            .describe('Retrieved claim record'),
+        history: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Chronological history of claim values'),
     });
     // 9. Tool: list_contradictions
-    registerTool('list_contradictions', 'Queries stored contradiction records from the database with filtering by resolution status, severity level, contradiction type, and confidence score. Returns enriched contradiction records with associated claim summaries and originating source details. Read-only operation. Use this tool to prioritize and triage conflicts.', {
+    registerTool('contradiction.conflicts.list', 'Queries stored contradiction records from the database with filtering by resolution status, severity level, contradiction type, and confidence score. Returns enriched contradiction records with associated claim summaries and originating source details. Read-only operation. Use this tool to prioritize and triage conflicts.', {
         status: z
             .enum(ContradictionStatuses)
             .optional()
@@ -677,9 +830,21 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        count: z.number().optional().describe('Number of contradictions returned in current page'),
+        total: z.number().optional().describe('Total count of contradictions matching filter'),
+        contradictions: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('List of contradiction records'),
     });
     // 10. Tool: get_contradiction
-    registerTool('get_contradiction', 'Retrieves complete details of a single contradiction record by ID, including full representations of both conflicting claims, originating source metadata, exact line evidence snippets, and chronological audit trail of all review and resolution actions. Read-only operation.', {
+    registerTool('contradiction.conflicts.get', 'Retrieves complete details of a single contradiction record by ID, including full representations of both conflicting claims, originating source metadata, exact line evidence snippets, and chronological audit trail of all review and resolution actions. Read-only operation.', {
         contradictionId: z
             .string()
             .min(1)
@@ -724,9 +889,24 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        contradiction: z
+            .record(z.string(), z.unknown())
+            .nullable()
+            .optional()
+            .describe('Full contradiction details'),
+        auditTrail: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('Review and resolution audit history'),
     });
     // 11. Tool: advise_resolution
-    registerTool('advise_resolution', 'Generates deterministic authority, freshness, and evidence comparison between conflicting claims to advise an AI agent or human reviewer on which claim likely represents current truth and recommended remediation steps. Read-only deterministic calculation.', {
+    registerTool('contradiction.conflicts.advise', 'Generates deterministic authority, freshness, and evidence comparison between conflicting claims to advise an AI agent or human reviewer on which claim likely represents current truth and recommended remediation steps. Read-only deterministic calculation.', {
         contradictionId: z
             .string()
             .min(1)
@@ -760,9 +940,25 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        contradictionId: z.string().optional().describe('ID of the analyzed contradiction'),
+        recommendedAction: z
+            .string()
+            .optional()
+            .describe('Recommended action: accept_source_a, accept_source_b, update_both, investigate'),
+        confidence: z.number().optional().describe('Confidence score from 0.0 to 1.0'),
+        rationale: z
+            .string()
+            .optional()
+            .describe('Authority and temporal rationale for the resolution advice'),
     });
     // 12. Tool: resolve_contradiction
-    registerTool('resolve_contradiction', 'Updates the lifecycle status and audit trail of a contradiction record. Supports marking as REVIEWED, resolving as RESOLVED with an authoritative chosen claim, dismissing as DISMISSED (acceptable divergence), or reopening back to OPEN. Preserves an immutable audit trail of reviewer identity, decision reason, and timestamp. Mutating operation.', {
+    registerTool('contradiction.conflicts.resolve', 'Updates the lifecycle status and audit trail of a contradiction record. Supports marking as REVIEWED, resolving as RESOLVED with an authoritative chosen claim, dismissing as DISMISSED (acceptable divergence), or reopening back to OPEN. Preserves an immutable audit trail of reviewer identity, decision reason, and timestamp. Mutating operation.', {
         contradictionId: z
             .string()
             .min(1)
@@ -848,6 +1044,15 @@ export function createMcpServer(options) {
                 ],
             };
         }
+    }, {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, {
+        id: z.string().optional().describe('ID of the updated contradiction'),
+        status: z.string().optional().describe('Updated contradiction lifecycle status'),
+        chosenClaimId: z.string().nullable().optional().describe('Authoritative claim ID chosen'),
     });
     // ==========================================
     // BACKWARDS COMPATIBILITY ROUTING SHIM
@@ -862,11 +1067,29 @@ export function createMcpServer(options) {
     rawRequestHandlers.set('tools/call', async (request, ctx) => {
         const toolName = request.params?.name;
         const args = request.params?.arguments || {};
-        if (toolName === 'health_check') {
-            request.params.name = 'check_health';
+        // Map canonical snake_case to dot-notation names
+        const canonicalMap = {
+            check_health: 'contradiction.health.check',
+            list_sources: 'contradiction.sources.list',
+            test_connection: 'contradiction.sources.test',
+            sync_source: 'contradiction.sources.sync',
+            scan_contradictions: 'contradiction.conflicts.scan',
+            analyze_claim_pair: 'contradiction.claims.analyze',
+            list_claims: 'contradiction.claims.list',
+            get_claim: 'contradiction.claims.get',
+            list_contradictions: 'contradiction.conflicts.list',
+            get_contradiction: 'contradiction.conflicts.get',
+            advise_resolution: 'contradiction.conflicts.advise',
+            resolve_contradiction: 'contradiction.conflicts.resolve',
+        };
+        if (canonicalMap[toolName]) {
+            request.params.name = canonicalMap[toolName];
+        }
+        else if (toolName === 'health_check') {
+            request.params.name = 'contradiction.health.check';
         }
         else if (toolName === 'list_connectors') {
-            request.params.name = 'list_sources';
+            request.params.name = 'contradiction.sources.list';
         }
         else if (toolName === 'test_github_connection') {
             if (!args.owner || !args.repo) {
@@ -880,7 +1103,7 @@ export function createMcpServer(options) {
                     ],
                 };
             }
-            request.params.name = 'test_connection';
+            request.params.name = 'contradiction.sources.test';
             request.params.arguments = {
                 connector: 'github',
                 target: `${args.owner}/${args.repo}`,
@@ -888,7 +1111,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'sync_document') {
-            request.params.name = 'sync_source';
+            request.params.name = 'contradiction.sources.sync';
             request.params.arguments = {
                 connector: 'document',
                 source: args.filePath,
@@ -901,7 +1124,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'sync_website') {
-            request.params.name = 'sync_source';
+            request.params.name = 'contradiction.sources.sync';
             request.params.arguments = {
                 connector: 'website',
                 source: args.url,
@@ -910,7 +1133,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'sync_github_repository') {
-            request.params.name = 'sync_source';
+            request.params.name = 'contradiction.sources.sync';
             request.params.arguments = {
                 connector: 'github',
                 source: `${args.owner}/${args.repo}`,
@@ -919,7 +1142,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'sync_sources') {
-            request.params.name = 'sync_source';
+            request.params.name = 'contradiction.sources.sync';
             request.params.arguments = {
                 connector: 'document',
                 source: 'batch',
@@ -928,7 +1151,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'scan_for_contradictions') {
-            request.params.name = 'scan_contradictions';
+            request.params.name = 'contradiction.conflicts.scan';
             request.params.arguments = {
                 limit: args.limit,
                 minConfidence: args.minConfidence,
@@ -936,14 +1159,14 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'scan_claim_for_contradictions') {
-            request.params.name = 'scan_contradictions';
+            request.params.name = 'contradiction.conflicts.scan';
             request.params.arguments = {
                 claimId: args.claimId,
                 minConfidence: args.minConfidence,
             };
         }
         else if (toolName === 'scan_source_for_contradictions') {
-            request.params.name = 'scan_contradictions';
+            request.params.name = 'contradiction.conflicts.scan';
             request.params.arguments = {
                 sourceId: args.sourceId,
                 minConfidence: args.minConfidence,
@@ -952,7 +1175,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'explain_claim_relationship') {
-            request.params.name = 'analyze_claim_pair';
+            request.params.name = 'contradiction.claims.analyze';
             request.params.arguments = {
                 claimAId: args.claimAId,
                 claimBId: args.claimBId,
@@ -960,7 +1183,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'review_contradiction') {
-            request.params.name = 'resolve_contradiction';
+            request.params.name = 'contradiction.conflicts.resolve';
             request.params.arguments = {
                 contradictionId: args.contradictionId,
                 action: 'REVIEW',
@@ -969,7 +1192,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'dismiss_contradiction') {
-            request.params.name = 'resolve_contradiction';
+            request.params.name = 'contradiction.conflicts.resolve';
             request.params.arguments = {
                 contradictionId: args.contradictionId,
                 action: 'DISMISS',
@@ -979,7 +1202,7 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'reopen_contradiction') {
-            request.params.name = 'resolve_contradiction';
+            request.params.name = 'contradiction.conflicts.resolve';
             request.params.arguments = {
                 contradictionId: args.contradictionId,
                 action: 'REOPEN',
@@ -989,19 +1212,23 @@ export function createMcpServer(options) {
             };
         }
         else if (toolName === 'get_contradiction_history') {
-            request.params.name = 'get_contradiction';
+            request.params.name = 'contradiction.conflicts.get';
             request.params.arguments = {
                 contradictionId: args.contradictionId,
                 includeAuditHistory: true,
             };
         }
         else if (toolName === 'get_claim_history') {
-            request.params.name = 'get_claim';
+            request.params.name = 'contradiction.claims.get';
             request.params.arguments = {
                 claimId: args.claimId,
                 includeHistory: true,
             };
         }
+        // Safety fallback: if request.params.name is still in canonicalMap, map to dot notation
+        if (canonicalMap[request.params.name]) {
+            request.params.name = canonicalMap[request.params.name];
+        }
         return canonicalCallHandler(request, ctx);
     });
     // --- MCP RESOURCES ---