trading212-mcp: Instructions file for Claude Code

Claude Agent Instructions

This document provides instructions for AI agents (like Claude) working with the Trading 212 MCP server codebase.

---

Project Overview

Name: trading212-mcp Type: Model Context Protocol (MCP) server Purpose: Enable AI agents to interact with Trading 212 investment accounts Language: TypeScript (Node.js) Architecture: MCP stdio server → Trading 212 REST API

---

Quick Context

What This Project Does

This MCP server provides 26 tools that allow AI agents to:

• View account balances and portfolio positions
• Place and manage orders (market, limit, stop, stop-limit)
• Search for tradeable instruments
• Create and manage investment pies
• Access historical data (orders, dividends, transactions)
• Export data for tax reporting

Core Components

1. src/index.ts - MCP server with 26 tool handlers
2. src/client.ts - Trading 212 API client wrapper
3. src/types.ts - Zod schemas and TypeScript types
4. src/cli.ts - CLI binary with argument parsing

---

Development Guidelines

When Adding New Features

1. API Endpoint Integration

If Trading 212 adds a new API endpoint:

Step 1: Add Zod schema in src/types.ts

export const NewFeatureSchema = z.object({
  id: z.number(),
  name: z.string(),
  // ... other fields
});

export type NewFeature = z.infer<typeof NewFeatureSchema>;

Step 2: Add client method in src/client.ts

async getNewFeature(): Promise<NewFeature> {
  return this.request('/equity/new-feature', {}, NewFeatureSchema);
}

Step 3: Add MCP tool in src/index.ts

Add to tools array:

{
  name: 'get_new_feature',
  description: 'Clear description of what this tool does',
  inputSchema: {
    type: 'object',
    properties: {
      // ... parameters
    },
    required: ['param1'],
  },
}

Add handler in CallToolRequestSchema:

case 'get_new_feature': {
  const { param1 } = args as { param1: string };
  const result = await client.getNewFeature();
  return {
    content: [{
      type: 'text',
      text: JSON.stringify(result, null, 2),
    }],
  };
}