PT-MCP (Paul Test Man Context Protocol)

Instructions

Implementation Reference

• src/tools/enrich-context.ts:46-175 (handler)

  Core handler function that executes the enrich_context tool logic: extracts entities, resolves YAGO knowledge graph entities, applies Schema.org annotations, computes confidence stats, and generates structured metadata.
  export async function enrichContext(args: EnrichContextArgs): Promise<EnrichedContext> { const { path, analysis_result, enrichment_level = 'standard', include_yago = true, include_schema = true, max_entities = 10, } = args; const result: EnrichedContext = { path, enrichment_metadata: { level: enrichment_level, timestamp: new Date().toISOString(), cache_hits: 0, yago_queries: 0, }, }; // If no analysis provided, we can only do minimal enrichment if (!analysis_result) { return { ...result, yago_entities: {}, schema_annotation: {}, json_ld: {}, }; } const db = await getDatabase(); const yagoResolver = getYAGOResolver(); const schemaMapper = getSchemaMapper(); // Extract entities from analysis const entities = extractEntitiesFromAnalysis(analysis_result, enrichment_level); // YAGO enrichment if (include_yago) { const yagoEntities: { [key: string]: YAGOEntity[] } = {}; let cacheHits = 0; let yagoQueries = 0; for (const [name, type] of entities.slice(0, max_entities)) { try { // Check if already cached const entity = db.findEntityByName(name); if (entity?.id) { const mapping = db.findYAGOMappingByEntityId(entity.id); if (mapping) { cacheHits++; } else { yagoQueries++; } } else { yagoQueries++; } // Resolve entity (uses cache automatically) const resolved = await yagoResolver.resolveEntity(name, 3); if (resolved.length > 0) { yagoEntities[name] = resolved; // Store in database if not exists if (!entity) { const entityId = await db.insertEntity({ name, type: type as EntityType, source_file: path, metadata: { detected_from: 'analysis' }, }); // Store high-confidence mapping if (resolved[0].confidence >= 0.9) { await db.upsertYAGOMapping({ entity_id: entityId, yago_uri: resolved[0].uri, yago_type: resolved[0].type, confidence: resolved[0].confidence, facts: { facts: resolved[0].facts }, }); } } } } catch (error) { console.error(`Failed to resolve YAGO entity for ${name}:`, error); } } result.yago_entities = yagoEntities; result.enrichment_metadata!.cache_hits = cacheHits; result.enrichment_metadata!.yago_queries = yagoQueries; // Calculate confidence stats const allEntities = Object.values(yagoEntities).flat(); if (allEntities.length > 0) { const autoLinked = allEntities.filter((e) => e.confidence >= 0.9).length; const avgConfidence = allEntities.reduce((sum, e) => sum + e.confidence, 0) / allEntities.length; result.confidence_stats = { total_entities: allEntities.length, auto_linked: autoLinked, needs_review: allEntities.length - autoLinked, avg_confidence: Math.round(avgConfidence * 100) / 100, }; } } // Schema.org enrichment if (include_schema) { const schemaType = schemaMapper.detectCodebaseType(analysis_result); const properties = schemaMapper.extractProperties(analysis_result); result.schema_annotation = { '@type': schemaType, ...properties, }; // Generate JSON-LD result.json_ld = schemaMapper.generateJSONLD({ entity_id: 0, // Temporary, will be assigned when stored schema_type: schemaType, properties, context_url: 'https://schema.org', }); } return result; }
• src/tools/enrich-context.ts:13-41 (schema)

  TypeScript interfaces defining input (EnrichContextArgs) and output (EnrichedContext) schemas for the tool.
  export interface EnrichContextArgs { path: string; analysis_result?: any; enrichment_level?: 'minimal' | 'standard' | 'comprehensive'; include_yago?: boolean; include_schema?: boolean; max_entities?: number; } export interface EnrichedContext { path: string; schema_annotation?: any; yago_entities?: { [key: string]: YAGOEntity[]; }; json_ld?: any; confidence_stats?: { total_entities: number; auto_linked: number; needs_review: number; avg_confidence: number; }; enrichment_metadata?: { level: string; timestamp: string; cache_hits: number; yago_queries: number; }; }
• src/tools/index.ts:30-41 (registration)

  Tool dispatch handler in switch statement that invokes the enrichContext function and formats the response for MCP.
  case "enrich_context": { const result = await enrichContext(args as any); const formatted = formatEnrichedContext(result); return { content: [ { type: "text", text: formatted, }, ], }; }
• src/index.ts:99-137 (schema)

  MCP tool registration schema in ListToolsRequestSchema response, defining input schema and description.
  name: "enrich_context", description: "Enrich codebase context with knowledge graph data from YAGO 4.5 and Schema.org annotations", inputSchema: { type: "object", properties: { path: { type: "string", description: "Root directory path", }, analysis_result: { type: "object", description: "Previous analysis result from analyze_codebase (optional)", }, enrichment_level: { type: "string", enum: ["minimal", "standard", "comprehensive"], description: "Level of enrichment (minimal: frameworks+languages, standard: +dependencies, comprehensive: +dev deps+patterns)", default: "standard", }, include_yago: { type: "boolean", description: "Include YAGO knowledge graph entity linking", default: true, }, include_schema: { type: "boolean", description: "Include Schema.org semantic annotations", default: true, }, max_entities: { type: "number", description: "Maximum entities to resolve from YAGO", default: 10, minimum: 1, maximum: 50, }, }, required: ["path"], },
• src/tools/enrich-context.ts:238-304 (helper)

  Helper function to format the EnrichedContext output into readable markdown text used in the tool response.
  export function formatEnrichedContext(context: EnrichedContext): string { const lines: string[] = []; lines.push(`# Enriched Context: ${context.path}`); lines.push(''); // Schema.org annotation if (context.schema_annotation) { lines.push('## Schema.org Annotation'); lines.push('```json'); lines.push(JSON.stringify(context.schema_annotation, null, 2)); lines.push('```'); lines.push(''); } // YAGO entities if (context.yago_entities && Object.keys(context.yago_entities).length > 0) { lines.push('## YAGO Knowledge Graph Entities'); lines.push(''); for (const [name, entities] of Object.entries(context.yago_entities)) { lines.push(`### ${name}`); for (const entity of entities) { lines.push(`- **${entity.label}** (confidence: ${entity.confidence.toFixed(2)})`); lines.push(` - Type: ${entity.type}`); lines.push(` - URI: ${entity.uri}`); if (entity.description) { lines.push(` - Description: ${entity.description}`); } if (entity.facts.length > 0) { lines.push(` - Facts: ${entity.facts.length} relationships`); } } lines.push(''); } } // Confidence stats if (context.confidence_stats) { lines.push('## Confidence Statistics'); lines.push(`- Total entities: ${context.confidence_stats.total_entities}`); lines.push(`- Auto-linked (≥0.9): ${context.confidence_stats.auto_linked}`); lines.push(`- Needs review (<0.9): ${context.confidence_stats.needs_review}`); lines.push(`- Average confidence: ${context.confidence_stats.avg_confidence}`); lines.push(''); } // Enrichment metadata if (context.enrichment_metadata) { lines.push('## Enrichment Metadata'); lines.push(`- Level: ${context.enrichment_metadata.level}`); lines.push(`- Timestamp: ${context.enrichment_metadata.timestamp}`); lines.push(`- Cache hits: ${context.enrichment_metadata.cache_hits}`); lines.push(`- YAGO queries: ${context.enrichment_metadata.yago_queries}`); lines.push(''); } // JSON-LD if (context.json_ld) { lines.push('## JSON-LD Structured Data'); lines.push('```json'); lines.push(JSON.stringify(context.json_ld, null, 2)); lines.push('```'); } return lines.join('\n'); }