managing-apps/assets/documentation/MCP-Architecture.md

# MCP (Model Context Protocol) Architecture

## Overview

This document describes the Model Context Protocol (MCP) architecture for the Managing trading platform. The architecture uses a dual-MCP approach: one internal C# MCP server for proprietary tools, and one open-source Node.js MCP server for community use.

## Architecture Decision

**Selected Option: Option 4 - Two MCP Servers by Deployment Model**

- **C# MCP Server**: Internal, in-process, proprietary tools
- **Node.js MCP Server**: Standalone, open-source, community-distributed

## Rationale

### Why Two MCP Servers?

1. **Proprietary vs Open Source Separation**
   - C# MCP: Contains proprietary business logic, trading algorithms, and internal tools
   - Node.js MCP: Public tools that can be open-sourced and contributed to by the community

2. **Deployment Flexibility**
   - C# MCP: Runs in-process within the API (fast, secure, no external access)
   - Node.js MCP: Community members install and run independently using their own API keys

3. **Community Adoption**
   - Node.js MCP can be published to npm
   - Community can contribute improvements
   - Works with existing Node.js MCP ecosystem

4. **Security & Access Control**
   - Internal tools stay private
   - Public tools use ManagingApiKeys for authentication
   - Each community member uses their own API key

## Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│ Your Infrastructure                                          │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐                    │
│  │ LLM Service  │─────▶│ C# MCP       │                    │
│  │ (Your API)   │      │ (Internal)   │                    │
│  └──────────────┘      └──────────────┘                    │
│         │                                                     │
│         │ HTTP + API Key                                     │
│         ▼                                                     │
│  ┌─────────────────────────────────────┐                    │
│  │ Public API Endpoints                │                    │
│  │ - /api/public/agents                │                    │
│  │ - /api/public/market-data           │                    │
│  │ - (Protected by ManagingApiKeys)    │                    │
│  └─────────────────────────────────────┘                    │
└─────────────────────────────────────────────────────────────┘
                    ▲
                    │ HTTP + API Key
                    │
┌─────────────────────────────────────────────────────────────┐
│ Community Infrastructure (Each User Runs Their Own)         │
│                                                              │
│  ┌──────────────┐      ┌──────────────┐                    │
│  │ LLM Client   │─────▶│ Node.js MCP  │                    │
│  │ (Claude, etc)│      │ (Open Source)│                    │
│  └──────────────┘      └──────────────┘                    │
│                              │                               │
│                              │ Uses ManagingApiKey           │
│                              │                               │
│                              ▼                               │
│                    ┌─────────────────┐                       │
│                    │ API Key Config  │                       │
│                    │ (User's Key)    │                       │
│                    └─────────────────┘                       │
└─────────────────────────────────────────────────────────────┘
```

## Component Details

### 1. C# MCP Server (Internal/Proprietary)

**Location**: `src/Managing.Mcp/`

**Characteristics**:
- Runs in-process within the API
- Contains proprietary trading logic
- Direct access to internal services via DI
- Fast execution (no network overhead)
- Not exposed externally

**Tools**:
- Internal trading operations
- Proprietary analytics
- Business-critical operations
- Admin functions

**Implementation**:
```csharp
[McpServerToolType]
public static class InternalTradingTools
{
    [McpServerTool, Description("Open a trading position (internal only)")]
    public static async Task<object> OpenPosition(
        ITradingService tradingService,
        IAccountService accountService,
        // ... internal services
    ) { }
}
```

### 2. Node.js MCP Server (Open Source/Community)

**Location**: `src/Managing.Mcp.Nodejs/` (future)

**Characteristics**:
- Standalone Node.js package
- Published to npm
- Community members install and run independently
- Connects to public API endpoints
- Uses ManagingApiKeys for authentication

**Tools**:
- Public agent summaries
- Market data queries
- Public analytics
- Read-only operations

**Distribution**:
- Published as `@yourorg/managing-mcp` on npm
- Community members install: `npm install -g @yourorg/managing-mcp`
- Each user configures their own API key

### 3. Public API Endpoints

**Location**: `src/Managing.Api/Controllers/PublicController.cs`

**Purpose**:
- Expose safe, public data to community
- Protected by ManagingApiKeys authentication
- Rate-limited per API key
- Audit trail for usage

**Endpoints**:
- `GET /api/public/agents/{agentName}` - Get public agent summary
- `GET /api/public/agents` - List public agents
- `GET /api/public/market-data/{ticker}` - Get market data

**Security**:
- API key authentication required
- Only returns public-safe data
- No internal business logic exposed

### 4. ManagingApiKeys Feature

**Status**: Not yet implemented

**Purpose**:
- Authenticate community members using Node.js MCP
- Control access to public API endpoints
- Enable rate limiting per user
- Track usage and analytics

**Implementation Requirements**:
- API key generation and management
- API key validation middleware
- User association with API keys
- Rate limiting per key
- Usage tracking and analytics

## Implementation Phases

### Phase 1: C# MCP Server (Current)

**Status**: To be implemented

**Tasks**:
- [ ] Install ModelContextProtocol NuGet package
- [ ] Create `Managing.Mcp` project structure
- [ ] Implement internal tools using `[McpServerTool]` attributes
- [ ] Create in-process MCP server service
- [ ] Integrate with LLM service
- [ ] Register in DI container

**Files to Create**:
- `src/Managing.Mcp/Managing.Mcp.csproj`
- `src/Managing.Mcp/Tools/InternalTradingTools.cs`
- `src/Managing.Mcp/Tools/InternalAdminTools.cs`
- `src/Managing.Application/LLM/IMcpService.cs`
- `src/Managing.Application/LLM/McpService.cs`

### Phase 2: Public API Endpoints

**Status**: To be implemented

**Tasks**:
- [ ] Create `PublicController` with public endpoints
- [ ] Implement `ApiKeyAuthenticationHandler`
- [ ] Create `[ApiKeyAuth]` attribute
- [ ] Design public data models (only safe data)
- [ ] Add rate limiting per API key
- [ ] Implement usage tracking

**Files to Create**:
- `src/Managing.Api/Controllers/PublicController.cs`
- `src/Managing.Api/Authentication/ApiKeyAuthenticationHandler.cs`
- `src/Managing.Api/Filters/ApiKeyAuthAttribute.cs`
- `src/Managing.Application/Abstractions/Services/IApiKeyService.cs`
- `src/Managing.Application/ApiKeys/ApiKeyService.cs`

### Phase 3: ManagingApiKeys Feature

**Status**: Not yet ready

**Tasks**:
- [ ] Design API key database schema
- [ ] Implement API key generation
- [ ] Create API key management UI/API
- [ ] Add API key validation
- [ ] Implement rate limiting
- [ ] Add usage analytics

**Database Schema** (proposed):
```sql
CREATE TABLE api_keys (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    key_hash VARCHAR(255) NOT NULL,
    name VARCHAR(255),
    created_at TIMESTAMP,
    last_used_at TIMESTAMP,
    expires_at TIMESTAMP,
    rate_limit_per_hour INTEGER,
    is_active BOOLEAN
);
```

### Phase 4: Node.js MCP Server (Future/Open Source)

**Status**: Future - after ManagingApiKeys is ready

**Tasks**:
- [ ] Create Node.js project structure
- [ ] Implement MCP server using `@modelcontextprotocol/sdk`
- [ ] Create API client with API key support
- [ ] Implement public tool handlers
- [ ] Create configuration system
- [ ] Write documentation
- [ ] Publish to npm

**Files to Create**:
- `src/Managing.Mcp.Nodejs/package.json`
- `src/Managing.Mcp.Nodejs/index.js`
- `src/Managing.Mcp.Nodejs/tools/public-tools.ts`
- `src/Managing.Mcp.Nodejs/api/client.ts`
- `src/Managing.Mcp.Nodejs/config/config.ts`
- `src/Managing.Mcp.Nodejs/README.md`

## Service Integration

### LLM Service Integration

Your internal LLM service only uses the C# MCP:

```csharp
public class LLMService : ILLMService
{
    private readonly IMcpService _internalMcpService; // C# only
    
    public async Task<LLMResponse> GenerateContentAsync(...)
    {
        // Only use internal C# MCP
        // Community uses Node.js MCP separately
    }
}
```

### Unified Service (Optional)

If you need to combine both MCPs in the future:

```csharp
public class UnifiedMcpService : IUnifiedMcpService
{
    private readonly IMcpService _internalMcpService;
    private readonly IMcpClientService _externalMcpClientService;
    
    // Routes tools to appropriate MCP based on prefix
    // internal:* -> C# MCP
    // public:* -> Node.js MCP (if needed internally)
}
```

## Configuration

### C# MCP Configuration

```json
// appsettings.json
{
  "Mcp": {
    "Internal": {
      "Enabled": true,
      "Type": "in-process"
    }
  }
}
```

### Node.js MCP Configuration (Community)

```json
// ~/.managing-mcp/config.json
{
  "apiUrl": "https://api.yourdomain.com",
  "apiKey": "user-api-key-here"
}
```

Or environment variables:
- `MANAGING_API_URL`
- `MANAGING_API_KEY`

## Benefits

### For Your Platform

1. **No Hosting Burden**: Community runs their own Node.js MCP instances
2. **API Key Control**: You control access via ManagingApiKeys
3. **Scalability**: Distributed across community
4. **Security**: Internal tools stay private
5. **Analytics**: Track usage per API key

### For Community

1. **Open Source**: Can contribute improvements
2. **Easy Installation**: Simple npm install
3. **Privacy**: Each user uses their own API key
4. **Flexibility**: Can customize or fork
5. **Ecosystem**: Works with existing Node.js MCP tools

## Security Considerations

### Internal C# MCP
- Runs in-process, no external access
- Direct service access via DI
- No network exposure
- Proprietary code stays private

### Public API Endpoints
- API key authentication required
- Rate limiting per key
- Only public-safe data returned
- Audit trail for all requests

### Node.js MCP
- Community members manage their own instances
- Each user has their own API key
- No access to internal tools
- Can be audited (open source)

## Future Enhancements

1. **MCP Registry**: List community-created tools
2. **Tool Marketplace**: Community can share custom tools
3. **Analytics Dashboard**: Usage metrics per API key
4. **Webhook Support**: Real-time updates via MCP
5. **Multi-tenant Support**: Organizations with shared API keys

## References

- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [C# SDK Documentation](https://github.com/modelcontextprotocol/csharp-sdk)
- [Node.js SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)

## Related Documentation

- [Architecture.drawio](Architecture.drawio) - Overall system architecture
- [Workers processing/](Workers%20processing/) - Worker architecture details

## Status

- **C# MCP Server**: Planning
- **Public API Endpoints**: Planning
- **ManagingApiKeys**: Not yet ready
- **Node.js MCP Server**: Future (after ManagingApiKeys)

## Notes

- The Node.js MCP will NOT be hosted by you - community members run it themselves
- Each community member uses their own ManagingApiKey
- Internal LLM service only uses C# MCP (in-process)
- Public API endpoints are the bridge between community and your platform