mcp-context-engineering
Version:
The intelligent context optimization system for AI coding assistants. Built with Cole's PRP methodology, Context Portal knowledge graphs, and production-ready MongoDB architecture.
522 lines (521 loc) • 17.2 kB
TypeScript
import { z } from 'zod';
import { Decision, ProgressEntry, SystemPattern, ContextLink } from '../../mongodb/models/contextPattern.js';
/**
* Knowledge Graph Manager - Context Portal Integration
*
* Implements Context Portal's sophisticated knowledge graph patterns:
* - Explicit relationship modeling with directional links
* - Hierarchical progress tracking with parent-child relationships
* - Structured decision capture with rationale and consequences
* - System pattern management with usage examples and trade-offs
* - Cross-workspace knowledge sharing with access control
* - Real-time graph traversal and relationship discovery
*/
export declare const GraphQuerySchema: z.ZodObject<{
workspace_id: z.ZodString;
query_type: z.ZodEnum<["traverse", "find_related", "pattern_search", "decision_path", "impact_analysis"]>;
source: z.ZodOptional<z.ZodObject<{
item_type: z.ZodString;
item_id: z.ZodString;
}, "strip", z.ZodTypeAny, {
item_type: string;
item_id: string;
}, {
item_type: string;
item_id: string;
}>>;
parameters: z.ZodOptional<z.ZodObject<{
relationship_types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
max_depth: z.ZodDefault<z.ZodNumber>;
include_metadata: z.ZodDefault<z.ZodBoolean>;
filter_by_status: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
min_relevance_score: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
max_depth: number;
include_metadata: boolean;
relationship_types?: string[] | undefined;
filter_by_status?: string[] | undefined;
min_relevance_score?: number | undefined;
}, {
relationship_types?: string[] | undefined;
max_depth?: number | undefined;
include_metadata?: boolean | undefined;
filter_by_status?: string[] | undefined;
min_relevance_score?: number | undefined;
}>>;
direction: z.ZodDefault<z.ZodEnum<["forward", "backward", "bidirectional"]>>;
limit: z.ZodDefault<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
workspace_id: string;
limit: number;
query_type: "traverse" | "find_related" | "pattern_search" | "decision_path" | "impact_analysis";
direction: "forward" | "backward" | "bidirectional";
source?: {
item_type: string;
item_id: string;
} | undefined;
parameters?: {
max_depth: number;
include_metadata: boolean;
relationship_types?: string[] | undefined;
filter_by_status?: string[] | undefined;
min_relevance_score?: number | undefined;
} | undefined;
}, {
workspace_id: string;
query_type: "traverse" | "find_related" | "pattern_search" | "decision_path" | "impact_analysis";
source?: {
item_type: string;
item_id: string;
} | undefined;
limit?: number | undefined;
parameters?: {
relationship_types?: string[] | undefined;
max_depth?: number | undefined;
include_metadata?: boolean | undefined;
filter_by_status?: string[] | undefined;
min_relevance_score?: number | undefined;
} | undefined;
direction?: "forward" | "backward" | "bidirectional" | undefined;
}>;
export type GraphQuery = z.infer<typeof GraphQuerySchema>;
export declare const GraphResultSchema: z.ZodObject<{
nodes: z.ZodArray<z.ZodObject<{
id: z.ZodString;
type: z.ZodString;
data: z.ZodAny;
metadata: z.ZodObject<{
created_at: z.ZodDate;
updated_at: z.ZodDate;
access_count: z.ZodDefault<z.ZodNumber>;
relevance_score: z.ZodOptional<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
created_at: Date;
updated_at: Date;
access_count: number;
relevance_score?: number | undefined;
}, {
created_at: Date;
updated_at: Date;
relevance_score?: number | undefined;
access_count?: number | undefined;
}>;
}, "strip", z.ZodTypeAny, {
type: string;
id: string;
metadata: {
created_at: Date;
updated_at: Date;
access_count: number;
relevance_score?: number | undefined;
};
data?: any;
}, {
type: string;
id: string;
metadata: {
created_at: Date;
updated_at: Date;
relevance_score?: number | undefined;
access_count?: number | undefined;
};
data?: any;
}>, "many">;
edges: z.ZodArray<z.ZodObject<{
source_id: z.ZodString;
target_id: z.ZodString;
relationship_type: z.ZodString;
description: z.ZodOptional<z.ZodString>;
weight: z.ZodDefault<z.ZodNumber>;
metadata: z.ZodObject<{
created_at: z.ZodDate;
last_traversed: z.ZodOptional<z.ZodDate>;
traversal_count: z.ZodDefault<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
created_at: Date;
traversal_count: number;
last_traversed?: Date | undefined;
}, {
created_at: Date;
last_traversed?: Date | undefined;
traversal_count?: number | undefined;
}>;
}, "strip", z.ZodTypeAny, {
relationship_type: string;
metadata: {
created_at: Date;
traversal_count: number;
last_traversed?: Date | undefined;
};
source_id: string;
target_id: string;
weight: number;
description?: string | undefined;
}, {
relationship_type: string;
metadata: {
created_at: Date;
last_traversed?: Date | undefined;
traversal_count?: number | undefined;
};
source_id: string;
target_id: string;
description?: string | undefined;
weight?: number | undefined;
}>, "many">;
query_metadata: z.ZodObject<{
total_nodes: z.ZodNumber;
total_edges: z.ZodNumber;
traversal_depth: z.ZodNumber;
processing_time_ms: z.ZodNumber;
cache_used: z.ZodBoolean;
}, "strip", z.ZodTypeAny, {
processing_time_ms: number;
cache_used: boolean;
total_nodes: number;
total_edges: number;
traversal_depth: number;
}, {
processing_time_ms: number;
cache_used: boolean;
total_nodes: number;
total_edges: number;
traversal_depth: number;
}>;
}, "strip", z.ZodTypeAny, {
nodes: {
type: string;
id: string;
metadata: {
created_at: Date;
updated_at: Date;
access_count: number;
relevance_score?: number | undefined;
};
data?: any;
}[];
edges: {
relationship_type: string;
metadata: {
created_at: Date;
traversal_count: number;
last_traversed?: Date | undefined;
};
source_id: string;
target_id: string;
weight: number;
description?: string | undefined;
}[];
query_metadata: {
processing_time_ms: number;
cache_used: boolean;
total_nodes: number;
total_edges: number;
traversal_depth: number;
};
}, {
nodes: {
type: string;
id: string;
metadata: {
created_at: Date;
updated_at: Date;
relevance_score?: number | undefined;
access_count?: number | undefined;
};
data?: any;
}[];
edges: {
relationship_type: string;
metadata: {
created_at: Date;
last_traversed?: Date | undefined;
traversal_count?: number | undefined;
};
source_id: string;
target_id: string;
description?: string | undefined;
weight?: number | undefined;
}[];
query_metadata: {
processing_time_ms: number;
cache_used: boolean;
total_nodes: number;
total_edges: number;
traversal_depth: number;
};
}>;
export type GraphResult = z.infer<typeof GraphResultSchema>;
export declare const WorkspaceContextSchema: z.ZodObject<{
workspace_id: z.ZodString;
project_id: z.ZodString;
product_context: z.ZodObject<{
project_overview: z.ZodString;
architecture_decisions: z.ZodArray<z.ZodString, "many">;
tech_stack: z.ZodArray<z.ZodString, "many">;
business_requirements: z.ZodArray<z.ZodString, "many">;
constraints: z.ZodArray<z.ZodString, "many">;
}, "strip", z.ZodTypeAny, {
tech_stack: string[];
project_overview: string;
architecture_decisions: string[];
business_requirements: string[];
constraints: string[];
}, {
tech_stack: string[];
project_overview: string;
architecture_decisions: string[];
business_requirements: string[];
constraints: string[];
}>;
active_context: z.ZodObject<{
current_features: z.ZodArray<z.ZodString, "many">;
active_issues: z.ZodArray<z.ZodString, "many">;
recent_changes: z.ZodArray<z.ZodObject<{
change_id: z.ZodString;
description: z.ZodString;
timestamp: z.ZodDate;
impact_level: z.ZodEnum<["low", "medium", "high"]>;
}, "strip", z.ZodTypeAny, {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}, {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}>, "many">;
session_goals: z.ZodArray<z.ZodString, "many">;
}, "strip", z.ZodTypeAny, {
recent_changes: {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}[];
current_features: string[];
active_issues: string[];
session_goals: string[];
}, {
recent_changes: {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}[];
current_features: string[];
active_issues: string[];
session_goals: string[];
}>;
access_control: z.ZodObject<{
workspace_type: z.ZodEnum<["private", "team", "organization", "public"]>;
access_level: z.ZodEnum<["read", "write", "admin"]>;
allowed_users: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
sharing_settings: z.ZodObject<{
allow_cross_workspace: z.ZodDefault<z.ZodBoolean>;
public_patterns: z.ZodDefault<z.ZodBoolean>;
}, "strip", z.ZodTypeAny, {
allow_cross_workspace: boolean;
public_patterns: boolean;
}, {
allow_cross_workspace?: boolean | undefined;
public_patterns?: boolean | undefined;
}>;
}, "strip", z.ZodTypeAny, {
workspace_type: "private" | "team" | "organization" | "public";
access_level: "read" | "write" | "admin";
sharing_settings: {
allow_cross_workspace: boolean;
public_patterns: boolean;
};
allowed_users?: string[] | undefined;
}, {
workspace_type: "private" | "team" | "organization" | "public";
access_level: "read" | "write" | "admin";
sharing_settings: {
allow_cross_workspace?: boolean | undefined;
public_patterns?: boolean | undefined;
};
allowed_users?: string[] | undefined;
}>;
metadata: z.ZodObject<{
created_at: z.ZodDate;
updated_at: z.ZodDate;
last_accessed: z.ZodDate;
version: z.ZodDefault<z.ZodNumber>;
}, "strip", z.ZodTypeAny, {
created_at: Date;
updated_at: Date;
version: number;
last_accessed: Date;
}, {
created_at: Date;
updated_at: Date;
last_accessed: Date;
version?: number | undefined;
}>;
}, "strip", z.ZodTypeAny, {
workspace_id: string;
project_id: string;
active_context: {
recent_changes: {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}[];
current_features: string[];
active_issues: string[];
session_goals: string[];
};
product_context: {
tech_stack: string[];
project_overview: string;
architecture_decisions: string[];
business_requirements: string[];
constraints: string[];
};
metadata: {
created_at: Date;
updated_at: Date;
version: number;
last_accessed: Date;
};
access_control: {
workspace_type: "private" | "team" | "organization" | "public";
access_level: "read" | "write" | "admin";
sharing_settings: {
allow_cross_workspace: boolean;
public_patterns: boolean;
};
allowed_users?: string[] | undefined;
};
}, {
workspace_id: string;
project_id: string;
active_context: {
recent_changes: {
description: string;
timestamp: Date;
change_id: string;
impact_level: "low" | "medium" | "high";
}[];
current_features: string[];
active_issues: string[];
session_goals: string[];
};
product_context: {
tech_stack: string[];
project_overview: string;
architecture_decisions: string[];
business_requirements: string[];
constraints: string[];
};
metadata: {
created_at: Date;
updated_at: Date;
last_accessed: Date;
version?: number | undefined;
};
access_control: {
workspace_type: "private" | "team" | "organization" | "public";
access_level: "read" | "write" | "admin";
sharing_settings: {
allow_cross_workspace?: boolean | undefined;
public_patterns?: boolean | undefined;
};
allowed_users?: string[] | undefined;
};
}>;
export type WorkspaceContext = z.infer<typeof WorkspaceContextSchema>;
/**
* Knowledge Graph Manager - Context Portal Integration
*/
export declare class KnowledgeGraphManager {
private mongoManager;
constructor();
/**
* Initialize workspace with Context Portal patterns
*/
initializeWorkspace(workspaceId: string, projectId: string, initialContext: Partial<WorkspaceContext>): Promise<WorkspaceContext>;
/**
* Create decision with Context Portal patterns
*/
createDecision(workspaceId: string, decision: Omit<Decision, 'id' | 'workspace_id' | 'date'>): Promise<Decision>;
/**
* Create progress entry with hierarchical relationships
*/
createProgressEntry(workspaceId: string, progress: Omit<ProgressEntry, 'id' | 'workspace_id' | 'date'>): Promise<ProgressEntry>;
/**
* Create system pattern with usage examples and trade-offs
*/
createSystemPattern(workspaceId: string, pattern: Omit<SystemPattern, 'id' | 'workspace_id'>): Promise<SystemPattern>;
/**
* Create explicit context link (Context Portal core pattern)
*/
createContextLink(workspaceId: string, link: Omit<ContextLink, 'workspace_id' | 'timestamp'>): Promise<ContextLink>;
/**
* Query knowledge graph with Context Portal patterns
*/
queryGraph(query: GraphQuery): Promise<GraphResult>;
/**
* Execute graph query with optimized traversal
*/
private executeGraphQuery;
/**
* Load node data by ID and type
*/
private loadNodeData;
/**
* Find connections for a node
*/
private findConnections;
/**
* Find patterns matching query
*/
private findPatterns;
/**
* Auto-link decisions to related progress entries (Context Portal pattern)
*/
private autoLinkDecisionToProgress;
/**
* Validate that link entities exist
*/
private validateLinkEntities;
/**
* Check if entity exists
*/
private entityExists;
/**
* Extract keywords for auto-linking
*/
private extractKeywords;
/**
* Get workspace analytics and health metrics
*/
getWorkspaceAnalytics(workspaceId: string): Promise<{
entity_counts: Record<string, number>;
relationship_stats: Record<string, number>;
activity_metrics: {
daily_changes: number;
decision_velocity: number;
pattern_reuse: number;
};
health_score: number;
}>;
/**
* Export workspace knowledge graph
*/
exportWorkspaceGraph(workspaceId: string, format?: 'json' | 'cypher' | 'graphml'): Promise<any>;
/**
* Convert graph result to Cypher format
*/
private convertToCypher;
/**
* Convert graph result to GraphML format
*/
private convertToGraphML;
}
export declare const knowledgeGraphManager: KnowledgeGraphManager;