Development Guide

// src/tools/my-new-server/src/server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/index.js';
import { 
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

export class MyNewMCPServer {
  private server: McpServer;

  constructor() {
    this.server = new McpServer({
      name: "my-new-server",
      version: "1.0.0"
    });

    this.setupHandlers();
  }

  private setupHandlers() {
    // List available tools
    this.server.setRequestHandler(ListToolsRequestSchema, async () => {
      return {
        tools: [
          {
            name: "my_custom_tool",
            description: "Performs custom business logic",
            inputSchema: {
              type: "object",
              properties: {
                input: {
                  type: "string",
                  description: "Input data for processing"
                },
                options: {
                  type: "object",
                  description: "Optional configuration"
                }
              },
              required: ["input"]
            }
          }
        ]
      };
    });

    // Handle tool calls
    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      switch (name) {
        case "my_custom_tool":
          return await this.handleCustomTool(args);
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    });
  }

  private async handleCustomTool(args: any) {
    // Implement your custom business logic here
    const result = await this.processCustomLogic(args.input, args.options);
    
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result)
        }
      ]
    };
  }

  private async processCustomLogic(input: string, options?: any) {
    // Your implementation here
    return {
      processed_input: input.toUpperCase(),
      timestamp: new Date().toISOString(),
      options: options || {}
    };
  }

  getServer() {
    return this.server;
  }
}

// src/api/src/orchestrator/llamaindex/tools/index.ts
export type McpServerName =
  | "echo-ping"
  | "customer-query"
  | "web-search"
  | "itinerary-planning"
  | "model-inference"
  | "code-evaluation"
  | "destination-recommendation"
  | "my-new-server";  // Add new server

export const McpToolsConfig = (): {
  [k in McpServerName]: McpServerDefinition;
} => ({
  // ... existing servers
  "my-new-server": {
    config: {
      url: process.env["MCP_MY_NEW_SERVER_URL"] + MCP_API_HTTP_PATH,
      type: "http",
      verbose: true,
    },
    id: "my-new-server",
    name: "My New Server",
  },
});

// src/api/src/orchestrator/llamaindex/index.ts
export async function setupAgents(filteredTools: McpServerDefinition[] = []) {
  // ... existing code

  if (tools["my-new-server"]) {
    const mcpServerConfig = mcpToolsConfig["my-new-server"];
    const tools = await mcp(mcpServerConfig.config).tools();
    
    const myNewAgent = agent({
      name: "MyNewAgent",
      systemPrompt: "Specialized agent for my new functionality. Always be helpful and accurate.",
      tools,
      llm,
      verbose,
    });
    
    agentsList.push(myNewAgent);
    handoffTargets.push(myNewAgent);
    toolsList.push(...tools);
  }

  // ... rest of function
}

// src/ui/src/app/components/my-new-component/my-new-component.component.ts
import { Component, Input, Output, EventEmitter, OnInit } from '@angular/core';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-my-new-component',
  standalone: true,
  imports: [CommonModule],
  template: `
    <div class="my-component">
      <h3>{{ title }}</h3>
      <div class="content">
        <ng-content></ng-content>
      </div>
      <button 
        (click)="handleAction()" 
        class="btn btn-primary"
        [disabled]="loading">
        {{ loading ? 'Processing...' : 'Action' }}
      </button>
    </div>
  `,
  styles: [`
    .my-component {
      @apply p-4 border rounded-lg shadow-sm;
    }
    .content {
      @apply my-4;
    }
    .btn {
      @apply px-4 py-2 rounded font-medium;
    }
    .btn-primary {
      @apply bg-blue-600 text-white hover:bg-blue-700;
    }
    .btn:disabled {
      @apply opacity-50 cursor-not-allowed;
    }
  `]
})
export class MyNewComponentComponent implements OnInit {
  @Input() title: string = 'Default Title';
  @Input() data: any;
  @Output() actionComplete = new EventEmitter<any>();

  loading = false;

  ngOnInit() {
    // Initialization logic
  }

  async handleAction() {
    this.loading = true;
    try {
      // Perform action
      const result = await this.processAction();
      this.actionComplete.emit(result);
    } catch (error) {
      console.error('Action failed:', error);
    } finally {
      this.loading = false;
    }
  }

  private async processAction(): Promise<any> {
    // Implementation
    return { success: true };
  }
}

// src/ui/src/app/app.routes.ts
import { Routes } from '@angular/router';
import { MyNewComponentComponent } from './components/my-new-component/my-new-component.component';

export const routes: Routes = [
  // ... existing routes
  {
    path: 'my-new-feature',
    component: MyNewComponentComponent,
    title: 'My New Feature'
  }
];

// src/api/src/routes/my-new-routes.ts
import { Router } from 'express';
import { z } from 'zod';

const router = Router();

// Request validation schemas
const MyRequestSchema = z.object({
  data: z.string(),
  options: z.object({
    format: z.enum(['json', 'xml']).optional()
  }).optional()
});

// POST /api/my-new-endpoint
router.post('/my-new-endpoint', async (req, res) => {
  try {
    // Validate request
    const validated = MyRequestSchema.parse(req.body);
    
    // Process request
    const result = await processMyNewFeature(validated);
    
    // Return response
    res.json({
      success: true,
      data: result,
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    res.status(400).json({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error'
    });
  }
});

// GET /api/my-new-endpoint/:id
router.get('/my-new-endpoint/:id', async (req, res) => {
  try {
    const { id } = req.params;
    const result = await getMyNewData(id);
    
    if (!result) {
      return res.status(404).json({
        success: false,
        error: 'Resource not found'
      });
    }
    
    res.json({
      success: true,
      data: result
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: 'Internal server error'
    });
  }
});

async function processMyNewFeature(data: any): Promise<any> {
  // Implementation
  return { processed: true, result: data };
}

async function getMyNewData(id: string): Promise<any> {
  // Implementation
  return { id, data: 'example' };
}

export default router;

// src/api/src/index.ts
import myNewRoutes from './routes/my-new-routes.js';

// ... existing code

// Register new routes
apiRouter.use('/my-new', myNewRoutes);

// ... rest of server setup

// src/api/src/__tests__/mcp-tools.test.ts
import { describe, it, expect, beforeEach, afterEach } from '@jest/globals';
import { mcpToolsList } from '../mcp/mcp-tools.js';

describe('MCP Tools', () => {
  beforeEach(() => {
    // Setup test environment
  });

  afterEach(() => {
    // Cleanup
  });

  it('should list all available tools', async () => {
    const mockConfig = [
      {
        id: 'test-server',
        name: 'Test Server',
        config: {
          url: 'http://localhost:3000/mcp',
          type: 'http' as const,
          verbose: false
        }
      }
    ];

    const tools = await mcpToolsList(mockConfig);
    
    expect(tools).toHaveLength(1);
    expect(tools[0].id).toBe('test-server');
    expect(tools[0].reachable).toBeDefined();
  });

  it('should handle unreachable servers gracefully', async () => {
    const mockConfig = [
      {
        id: 'unreachable-server',
        name: 'Unreachable Server',
        config: {
          url: 'http://nonexistent:3000/mcp',
          type: 'http' as const,
          verbose: false
        }
      }
    ];

    const tools = await mcpToolsList(mockConfig);
    
    expect(tools[0].reachable).toBe(false);
    expect(tools[0].error).toBeDefined();
  });
});

// src/ui/src/app/components/my-component/my-component.component.spec.ts
import { ComponentFixture, TestBed } from '@angular/core/testing';
import { MyNewComponentComponent } from './my-new-component.component';

describe('MyNewComponentComponent', () => {
  let component: MyNewComponentComponent;
  let fixture: ComponentFixture<MyNewComponentComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [MyNewComponentComponent]
    }).compileComponents();

    fixture = TestBed.createComponent(MyNewComponentComponent);
    component = fixture.componentInstance;
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });

  it('should emit action complete event', async () => {
    spyOn(component.actionComplete, 'emit');
    
    await component.handleAction();
    
    expect(component.actionComplete.emit).toHaveBeenCalledWith(
      jasmine.objectContaining({ success: true })
    );
  });

  it('should handle loading state', async () => {
    expect(component.loading).toBe(false);
    
    const actionPromise = component.handleAction();
    expect(component.loading).toBe(true);
    
    await actionPromise;
    expect(component.loading).toBe(false);
  });
});

// src/api/src/__tests__/integration/chat.test.ts
import request from 'supertest';
import { app } from '../index.js';

describe('Chat API Integration', () => {
  it('should process chat request with tools', async () => {
    const response = await request(app)
      .post('/api/chat')
      .send({
        message: 'Plan a trip to Tokyo',
        tools: [
          {
            id: 'echo-ping',
            name: 'Echo Test',
            selected: true
          }
        ]
      })
      .expect(200);

    // For SSE responses, check headers
    expect(response.headers['content-type']).toContain('text/event-stream');
  });

  it('should validate request body', async () => {
    const response = await request(app)
      .post('/api/chat')
      .send({
        // Missing required fields
      })
      .expect(400);

    expect(response.body.error).toBeDefined();
  });
});

// e2e/tests/user-journey.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Travel Planning User Journey', () => {
  test('should complete full travel planning flow', async ({ page }) => {
    // Navigate to application
    await page.goto('http://localhost:4200');

    // Enter travel query
    await page.fill('[data-testid="message-input"]', 'Plan a 5-day trip to Paris');

    // Select tools
    await page.check('[data-testid="tool-destination-recommendation"]');
    await page.check('[data-testid="tool-itinerary-planning"]');

    // Submit request
    await page.click('[data-testid="submit-button"]');

    // Wait for response
    await page.waitForSelector('[data-testid="response-content"]', {
      timeout: 30000
    });

    // Verify response contains expected content
    const responseText = await page.textContent('[data-testid="response-content"]');
    expect(responseText).toContain('Paris');
    expect(responseText).toContain('itinerary');
  });

  test('should handle tool selection changes', async ({ page }) => {
    await page.goto('http://localhost:4200');

    // Initially no tools selected
    const selectedTools = await page.$$('[data-testid^="tool-"]:checked');
    expect(selectedTools.length).toBe(0);

    // Select tools
    await page.check('[data-testid="tool-echo-ping"]');
    await page.check('[data-testid="tool-web-search"]');

    // Verify selection
    const newSelectedTools = await page.$$('[data-testid^="tool-"]:checked');
    expect(newSelectedTools.length).toBe(2);
  });
});

// tests/performance/load-test.ts
import { check } from 'k6';
import http from 'k6/http';

export let options = {
  stages: [
    { duration: '2m', target: 10 },   // Ramp up
    { duration: '5m', target: 10 },   // Stay at 10 users
    { duration: '2m', target: 20 },   // Ramp up to 20 users
    { duration: '5m', target: 20 },   // Stay at 20 users
    { duration: '2m', target: 0 },    // Ramp down
  ],
};

export default function() {
  const payload = JSON.stringify({
    message: 'Plan a quick weekend trip',
    tools: [
      { id: 'echo-ping', name: 'Echo Test', selected: true }
    ]
  });

  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  const response = http.post('http://localhost:4000/api/chat', payload, params);

  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 5s': (r) => r.timings.duration < 5000,
  });
}

// Set breakpoints in your code and use the Debug API configuration
// Launch configuration already provided in .vscode/launch.json

// Example debugging session
const result = await mcpToolsList(toolConfigs);
// Set breakpoint here to inspect result
console.log('Tools result:', result);

// src/api/src/utils/logger.ts
import { trace } from '@opentelemetry/api';

const tracer = trace.getTracer('api-debug');

export function debugLog(message: string, data?: any) {
  const span = tracer.startSpan('debug-log');
  
  console.log(`[DEBUG] ${new Date().toISOString()} - ${message}`, data);
  
  span.addEvent('debug-log', {
    message,
    data: JSON.stringify(data)
  });
  
  span.end();
}

// Usage in your code
debugLog('Processing MCP tool call', { toolName, args });

// Enable verbose logging for MCP clients
const mcpClient = new MCPHTTPClient(
  "debug-client",
  serverUrl,
  accessToken,
  { verbose: true }  // Enable detailed logging
);

// Log all MCP communication
mcpClient.on('request', (request) => {
  console.log('MCP Request:', JSON.stringify(request, null, 2));
});

mcpClient.on('response', (response) => {
  console.log('MCP Response:', JSON.stringify(response, null, 2));
});

// Add debugging helpers to your component
export class MyComponent {
  ngOnInit() {
    // Add component to global scope for debugging
    (window as any).debugComponent = this;
    
    // Log component state
    console.log('Component initialized:', this);
  }
  
  // Add debug method
  debug() {
    return {
      state: this.getState(),
      methods: Object.getOwnPropertyNames(Object.getPrototypeOf(this))
    };
  }
}

// In browser console:
// debugComponent.debug()

// src/ui/src/app/services/api.service.ts
export class ApiService {
  async streamChatMessage(message: string, tools: Tools[]) {
    // Add request/response logging
    console.log('API Request:', { message, tools });
    
    try {
      const response = await fetch(`${this.apiUrl}/api/chat`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ message, tools }),
      });

      console.log('API Response Status:', response.status);
      console.log('API Response Headers:', response.headers);

      // ... rest of implementation
    } catch (error) {
      console.error('API Error:', error);
      throw error;
    }
  }
}

// Use PascalCase for classes and interfaces
class TravelAgentService {}
interface UserPreferences {}

// Use camelCase for variables, functions, and methods
const userName = 'john';
function processRequest() {}

// Use SCREAMING_SNAKE_CASE for constants
const MAX_RETRY_ATTEMPTS = 3;
const API_ENDPOINTS = {
  CHAT: '/api/chat',
  TOOLS: '/api/tools'
} as const;

// Use kebab-case for file names
// good: travel-agent.service.ts
// bad: TravelAgentService.ts

// File organization
import { standardLibraries } from 'node:path';
import { thirdPartyLibraries } from 'express';
import { localImports } from './local-file.js';

// Type definitions first
interface RequestData {
  message: string;
  tools: ToolSelection[];
}

// Constants
const DEFAULT_TIMEOUT = 30000;

// Main implementation
export class ServiceClass {
  // Private properties first
  private readonly config: Config;
  
  // Public properties
  public readonly name: string;
  
  // Constructor
  constructor(config: Config) {
    this.config = config;
    this.name = config.serviceName;
  }
  
  // Public methods
  public async processRequest(data: RequestData): Promise<Response> {
    // Implementation
  }
  
  // Private methods last
  private validateRequest(data: RequestData): boolean {
    // Implementation
  }
}

// Create custom error classes
export class MCPServerError extends Error {
  constructor(
    message: string,
    public readonly serverName: string,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'MCPServerError';
  }
}

// Use proper error handling patterns
async function callMCPTool(toolName: string, args: unknown): Promise<ToolResult> {
  try {
    const result = await mcpClient.callTool(toolName, args);
    return result;
  } catch (error) {
    if (error instanceof MCPServerError) {
      // Handle MCP-specific errors
      throw error;
    } else if (error instanceof Error) {
      // Wrap unknown errors
      throw new MCPServerError(
        `Tool call failed: ${error.message}`,
        toolName,
        error
      );
    } else {
      // Handle non-Error objects
      throw new MCPServerError(
        `Tool call failed with unknown error`,
        toolName
      );
    }
  }
}

@Component({
  selector: 'app-travel-planner',
  standalone: true,
  imports: [CommonModule, FormsModule],
  template: `
    <!-- Template content -->
  `,
  styles: [`
    /* Component-specific styles */
  `],
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class TravelPlannerComponent implements OnInit, OnDestroy {
  // Input properties
  @Input() config!: PlannerConfig;
  
  // Output events
  @Output() planCompleted = new EventEmitter<TravelPlan>();
  
  // ViewChild references
  @ViewChild('plannerForm') plannerForm!: ElementRef;
  
  // Public properties (template-bound)
  isLoading = signal(false);
  travelPlan = signal<TravelPlan | null>(null);
  
  // Private properties
  private destroy$ = new Subject<void>();
  
  constructor(
    private apiService: ApiService,
    private cd: ChangeDetectorRef
  ) {}
  
  ngOnInit() {
    this.initializeComponent();
  }
  
  ngOnDestroy() {
    this.destroy$.next();
    this.destroy$.complete();
  }
  
  // Public methods (template-bound)
  onSubmitPlan(formData: FormData) {
    // Implementation
  }
  
  // Private methods
  private initializeComponent() {
    // Implementation
  }
}

@Injectable({
  providedIn: 'root'
})
export class TravelPlanService {
  private readonly apiUrl = environment.apiServerUrl;
  private readonly httpClient = inject(HttpClient);
  
  // Public methods
  async createTravelPlan(preferences: TravelPreferences): Promise<TravelPlan> {
    return firstValueFrom(
      this.httpClient.post<TravelPlan>(`${this.apiUrl}/api/travel-plans`, preferences)
        .pipe(
          timeout(30000),
          retry(3),
          catchError(this.handleError)
        )
    );
  }
  
  // Private methods
  private handleError = (error: HttpErrorResponse): Observable<never> => {
    console.error('Service error:', error);
    return throwError(() => new Error('Service operation failed'));
  };
}

/**
 * Processes a travel query using AI agents and MCP tools
 * 
 * @param message - The user's travel query in natural language
 * @param tools - Selected MCP tools to use for processing
 * @param options - Optional configuration for the request
 * @returns A stream of processing events and final result
 * 
 * @example
 * ```typescript
 * const stream = await processTravelQuery(
 *   "Plan a 5-day trip to Japan",
 *   [{ id: "destination-recommendation", selected: true }],
 *   { timeout: 30000 }
 * );
 * 
 * for await (const event of stream) {
 *   console.log('Processing event:', event);
 * }
 * ```
 * 
 * @throws {ValidationError} When input parameters are invalid
 * @throws {MCPServerError} When MCP tool communication fails
 */
export async function processTravelQuery(
  message: string,
  tools: ToolSelection[],
  options?: ProcessingOptions
): Promise<AsyncIterable<ProcessingEvent>> {
  // Implementation
}

// Use proper cleanup for event listeners and subscriptions
export class EventManager {
  private subscriptions: Subscription[] = [];
  
  subscribe(event: Observable<any>) {
    const sub = event.subscribe(handler);
    this.subscriptions.push(sub);
    return sub;
  }
  
  cleanup() {
    this.subscriptions.forEach(sub => sub.unsubscribe());
    this.subscriptions = [];
  }
}

// Avoid memory leaks in long-running processes
async function processLargeDataset(data: LargeDataset) {
  const batchSize = 1000;
  
  for (let i = 0; i < data.length; i += batchSize) {
    const batch = data.slice(i, i + batchSize);
    await processBatch(batch);
    
    // Allow garbage collection
    if (i % 10000 === 0) {
      await new Promise(resolve => setImmediate(resolve));
    }
  }
}

// Use OnPush change detection strategy
@Component({
  changeDetection: ChangeDetectionStrategy.OnPush
})
export class OptimizedComponent {
  // Use signals for reactive data
  data = signal<Data[]>([]);
  
  // Use computed for derived state
  filteredData = computed(() => 
    this.data().filter(item => item.isVisible)
  );
  
  // Use trackBy for ngFor
  trackById(index: number, item: DataItem): string {
    return item.id;
  }
}

// Use lazy loading for routes
const routes: Routes = [
  {
    path: 'admin',
    loadComponent: () => import('./admin/admin.component').then(m => m.AdminComponent)
  }
];

// Use dynamic imports for heavy libraries
async function loadHeavyLibrary() {
  const { HeavyLibrary } = await import('heavy-library');
  return new HeavyLibrary();
}