@swoft/platform-contracts/NAVIGATION-INTERFACE-ENHANCEMENTS.md

DDD-compliant dependency injection contracts for Swoft platform - Defines clean architecture boundaries

# NavigationHints Interface Enhancements v1.1.0

## Summary

Enhanced the platform contracts NavigationHints interface based on learnings from DevOps MCP implementation. The interface is now ready for consistent rollout across all MCP servers.

## Key Enhancements Made

### 1. Complex Context Handoffs

**New**: Added `context_handoffs` field to `NavigationHints` interface

```typescript
context_handoffs?: Record<string, ContextHandoff>;
```

**Impact**: Enables seamless cross-MCP workflows with pre-populated data and intelligent coordination.

### 2. Workflow Context Intelligence

**New**: Added `ContextHandoff` interface with rich workflow context

```typescript
interface ContextHandoff {
  mcp: string;
  tool?: string;
  suggested_action: string;
  scenario: string;
  pre_populated: Record<string, unknown>;
  workflow_context: {
    operation_type: OperationType;
    severity: SeverityLevel;
    service_context?: Record<string, unknown>;
    domain_context?: Record<string, unknown>;
    user_context?: Record<string, unknown>;
    project_context?: Record<string, unknown>;
  };
}
```

**Impact**: Supports intelligent coordination between MCP servers with context-aware handoffs.

### 3. Standardized Type System

**New**: Added comprehensive type definitions

- `OperationType`: 'incident' | 'maintenance' | 'discovery' | 'monitoring' | 'development' | 'planning'
- `SeverityLevel`: 'low' | 'medium' | 'high' | 'critical'
- `McpServerId`: Canonical list of all MCP servers
- `DomainContext`: Supported domain contexts
- `WorkflowPhase`: Development and operational phases

**Impact**: Ensures consistency across all MCP server implementations.

### 4. Enhanced Contextual Information

**Enhanced**: Extended `ContextualInformation` with domain-specific context

```typescript
boundedContextInfo?: {
  gtd?: { /* GTD-specific context */ };
  party?: { /* Party management context */ };
  devops?: { /* DevOps context */ };
  ddd?: { /* DDD modeling context */ };
};
```

**Impact**: Enables domain-specific navigation hints while maintaining interface consistency.

### 5. Factory Patterns

**New**: Added `ContextHandoffFactory` interface for common scenarios

```typescript
interface ContextHandoffFactory {
  createIncidentHandoff(
    targetMcp: McpServerId,
    severity: SeverityLevel,
    context: Record<string, unknown>
  ): ContextHandoff;
  createMaintenanceHandoff(
    targetMcp: McpServerId,
    maintenanceType: string,
    context: Record<string, unknown>
  ): ContextHandoff;
  createDiscoveryHandoff(
    targetMcp: McpServerId,
    discoveryGoal: string,
    context: Record<string, unknown>
  ): ContextHandoff;
  createDevelopmentHandoff(
    targetMcp: McpServerId,
    developmentPhase: WorkflowPhase,
    context: Record<string, unknown>
  ): ContextHandoff;
  createPlanningHandoff(
    targetMcp: McpServerId,
    planningScope: string,
    context: Record<string, unknown>
  ): ContextHandoff;
}
```

**Impact**: Provides standardized patterns for creating cross-MCP handoffs.

## Comparison: Before vs After

### DevOps MCP Implementation (Before Platform Enhancement)

```typescript
interface NavigationHints {
  next_steps: string[];
  related_tools: string[];
  cross_mcp?: string[];
  context_handoffs?: Record<
    string,
    {
      mcp: string;
      tool?: string;
      suggested_action: string;
      pre_populated: Record<string, any>;
      scenario: string;
      workflow_context: {
        operation_type: 'incident' | 'maintenance' | 'discovery' | 'monitoring';
        severity: 'low' | 'medium' | 'high' | 'critical';
        service_context: Record<string, any>;
      };
    }
  >;
}
```

### Platform Contracts (After Enhancement)

```typescript
interface NavigationHints {
  next_steps: string[];
  related_tools: ToolReference[];
  cross_mcp: CrossMcpReference[];
  git_aware: GitNavigationHint[];
  context: ContextualInformation;
  context_handoffs?: Record<string, ContextHandoff>;
  metadata?: {
    generated_at?: string;
    confidence?: number;
    source?: string;
    version?: string;
  };
}
```

## Rollout Plan for Other MCP Servers

### 1. GTD MCP Server

**Domain-Specific Enhancements Needed**:

- Context handoffs for project creation → DDD domain modeling
- Task completion → DevOps deployment workflows
- Weekly review → cross-domain maintenance planning

**Implementation Priority**: High (coordinates all other domains)

### 2. Party MCP Server

**Domain-Specific Enhancements Needed**:

- Person management → project assignment workflows
- Organization context → team coordination handoffs
- Role assignments → capability-based task distribution

**Implementation Priority**: Medium

### 3. DDD MCP Server

**Domain-Specific Enhancements Needed**:

- Domain creation → implementation project handoffs
- Aggregate design → code generation workflows
- Bounded context analysis → service architecture planning

**Implementation Priority**: Medium

### 4. Frontend/Backend Development MCPs

**Domain-Specific Enhancements Needed**:

- Development tasks → testing and deployment coordination
- Bug reports → incident management workflows
- Feature completion → documentation and review handoffs

**Implementation Priority**: Low (can build on foundation)

## Breaking Changes

None. All enhancements are backward compatible additions.

## Migration Guide

1. Update MCP server dependencies to `@swoft/platform-contracts@^1.1.0`
2. Implement the enhanced `NavigationHints` interface
3. Add `context_handoffs` support for cross-MCP workflows
4. Use standardized types (`OperationType`, `SeverityLevel`, etc.)
5. Enhance domain-specific context in `boundedContextInfo`

## Verification

- ✅ Interface compiles successfully
- ✅ Example implementations work correctly
- ✅ Published to Verdaccio registry
- ✅ Ready for rollout to all MCP servers

## Next Steps

1. Roll out enhanced interface to GTD MCP server first
2. Implement in Party MCP server
3. Add to DDD MCP server
4. Create cross-MCP workflow integration tests
5. Document domain-specific best practices for each MCP server

---

**Version**: 1.1.0  
**Date**: 2025-08-02  
**Status**: Ready for Production Rollout