473 lines
14 KiB
Markdown
473 lines
14 KiB
Markdown
# User MCP Server - Resource Architecture
|
|
|
|
The user's MCP server container owns **all** conversation history, RAG, and contextual data. The platform gateway is a thin, stateless orchestrator that only holds the Anthropic API key.
|
|
|
|
## Architecture Principle
|
|
|
|
**User Container = Fat Context**
|
|
- Conversation history (PostgreSQL/SQLite)
|
|
- RAG system (embeddings, vector search)
|
|
- User preferences and custom prompts
|
|
- Trading context (positions, watchlists, alerts)
|
|
- All user-specific data
|
|
|
|
**Platform Gateway = Thin Orchestrator**
|
|
- Anthropic API key (platform pays for LLM)
|
|
- Session management (WebSocket/Telegram connections)
|
|
- MCP client connection pooling
|
|
- Tool routing (platform vs user tools)
|
|
- **Zero conversation state stored**
|
|
|
|
## MCP Resources for Context Injection
|
|
|
|
Resources are **read-only** data sources that provide context to the LLM. They're fetched before each Claude API call and embedded in the conversation.
|
|
|
|
### Standard Context Resources
|
|
|
|
#### 1. `context://user-profile`
|
|
**Purpose:** User's trading background and preferences
|
|
|
|
**MIME Type:** `text/plain`
|
|
|
|
**Example Content:**
|
|
```
|
|
User Profile:
|
|
- Trading experience: Intermediate
|
|
- Preferred timeframes: 1h, 4h, 1d
|
|
- Risk tolerance: Medium
|
|
- Focus: Swing trading with technical indicators
|
|
- Favorite indicators: RSI, MACD, Bollinger Bands
|
|
- Active pairs: BTC/USDT, ETH/USDT, SOL/USDT
|
|
```
|
|
|
|
**Implementation Notes:**
|
|
- Stored in user's database `user_preferences` table
|
|
- Updated via preference management tools
|
|
- Includes inferred data from usage patterns
|
|
|
|
---
|
|
|
|
#### 2. `context://conversation-summary`
|
|
**Purpose:** Semantic summary of recent conversation with RAG-enhanced context
|
|
|
|
**MIME Type:** `text/plain`
|
|
|
|
**Example Content:**
|
|
```
|
|
Recent Conversation Summary:
|
|
|
|
Last 10 messages (summarized):
|
|
- User asked about moving average crossover strategies
|
|
- Discussed backtesting parameters for BTC/USDT
|
|
- Reviewed risk management with 2% position sizing
|
|
- Explored adding RSI filter to reduce false signals
|
|
|
|
Relevant past discussions (RAG search):
|
|
- 2 weeks ago: Similar strategy development on ETH/USDT
|
|
- 1 month ago: User prefers simple strategies over complex ones
|
|
- Past preference: Avoid strategies with >5 indicators
|
|
|
|
Current focus: Optimizing MA crossover with momentum filter
|
|
```
|
|
|
|
**Implementation Notes:**
|
|
- Last N messages stored in `conversation_history` table
|
|
- RAG search against embeddings of past conversations
|
|
- Semantic search using user's current message as query
|
|
- ChromaDB/pgvector for embedding storage
|
|
- Summary generated on-demand (can be cached for 1-5 minutes)
|
|
|
|
**RAG Integration:**
|
|
```python
|
|
async def get_conversation_summary() -> str:
|
|
# Get recent messages
|
|
recent = await db.get_recent_messages(limit=50)
|
|
|
|
# Semantic search for relevant context
|
|
relevant = await rag.search_conversation_history(
|
|
query=recent[-1].content, # Last user message
|
|
limit=5,
|
|
min_score=0.7
|
|
)
|
|
|
|
# Build summary
|
|
return build_summary(recent[-10:], relevant)
|
|
```
|
|
|
|
---
|
|
|
|
#### 3. `context://workspace-state`
|
|
**Purpose:** Current trading workspace (chart, positions, watchlist)
|
|
|
|
**MIME Type:** `application/json`
|
|
|
|
**Example Content:**
|
|
```json
|
|
{
|
|
"currentChart": {
|
|
"ticker": "BINANCE:BTC/USDT",
|
|
"timeframe": "1h",
|
|
"indicators": ["SMA(20)", "RSI(14)", "MACD(12,26,9)"]
|
|
},
|
|
"watchlist": ["BTC/USDT", "ETH/USDT", "SOL/USDT"],
|
|
"openPositions": [
|
|
{
|
|
"ticker": "BTC/USDT",
|
|
"side": "long",
|
|
"size": 0.1,
|
|
"entryPrice": 45000,
|
|
"currentPrice": 46500,
|
|
"unrealizedPnL": 150
|
|
}
|
|
],
|
|
"recentAlerts": [
|
|
{
|
|
"type": "price_alert",
|
|
"message": "BTC/USDT crossed above $46,000",
|
|
"timestamp": "2025-01-15T10:30:00Z"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Implementation Notes:**
|
|
- Synced from web client chart state
|
|
- Updated via WebSocket sync protocol
|
|
- Includes active indicators on current chart
|
|
- Position data from trading system
|
|
|
|
---
|
|
|
|
#### 4. `context://system-prompt`
|
|
**Purpose:** User's custom instructions and preferences for AI behavior
|
|
|
|
**MIME Type:** `text/plain`
|
|
|
|
**Example Content:**
|
|
```
|
|
Custom Instructions:
|
|
- Be concise and data-driven
|
|
- Always show risk/reward ratios
|
|
- Prefer simple strategies over complex ones
|
|
- When suggesting trades, include stop-loss and take-profit levels
|
|
- Explain your reasoning in trading decisions
|
|
```
|
|
|
|
**Implementation Notes:**
|
|
- User-editable in preferences UI
|
|
- Appended **last** to system prompt (highest priority)
|
|
- Can override platform defaults
|
|
- Stored in `user_preferences.custom_prompt` field
|
|
|
|
---
|
|
|
|
## MCP Tools for Actions
|
|
|
|
Tools are for **actions** that have side effects. These are **not** used for context fetching.
|
|
|
|
### Conversation Management
|
|
- `save_message(role, content, timestamp)` - Save message to history
|
|
- `search_conversation(query, limit)` - Explicit semantic search (for user queries like "what did we discuss about BTC?")
|
|
|
|
### Strategy & Indicators
|
|
- `list_strategies()` - List user's strategies
|
|
- `read_strategy(name)` - Get strategy code
|
|
- `write_strategy(name, code)` - Save strategy
|
|
- `run_backtest(strategy, params)` - Execute backtest
|
|
|
|
### Trading
|
|
- `get_watchlist()` - Get watchlist (action that may trigger sync)
|
|
- `execute_trade(params)` - Execute trade order
|
|
- `get_positions()` - Fetch current positions from exchange
|
|
|
|
### Sandbox
|
|
- `run_python(code)` - Execute Python code with data science libraries
|
|
|
|
---
|
|
|
|
## Gateway Harness Flow
|
|
|
|
```typescript
|
|
// gateway/src/harness/agent-harness.ts
|
|
|
|
async handleMessage(message: InboundMessage): Promise<OutboundMessage> {
|
|
// 1. Fetch context resources from user's MCP
|
|
const contextResources = await fetchContextResources([
|
|
'context://user-profile',
|
|
'context://conversation-summary', // <-- RAG happens here
|
|
'context://workspace-state',
|
|
'context://system-prompt',
|
|
]);
|
|
|
|
// 2. Build system prompt from resources
|
|
const systemPrompt = buildSystemPrompt(contextResources);
|
|
|
|
// 3. Build messages with embedded conversation context
|
|
const messages = buildMessages(message, contextResources);
|
|
|
|
// 4. Get tools from MCP
|
|
const tools = await mcpClient.listTools();
|
|
|
|
// 5. Call Claude with embedded context
|
|
const response = await anthropic.messages.create({
|
|
model: 'claude-3-5-sonnet-20241022',
|
|
system: systemPrompt, // <-- User profile + workspace + custom prompt
|
|
messages, // <-- Conversation summary from RAG
|
|
tools,
|
|
});
|
|
|
|
// 6. Save to user's MCP (tool call)
|
|
await mcpClient.callTool('save_message', { role: 'user', content: message.content });
|
|
await mcpClient.callTool('save_message', { role: 'assistant', content: response });
|
|
|
|
return response;
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## User MCP Server Implementation (Python)
|
|
|
|
### Resource Handler
|
|
|
|
```python
|
|
# user-mcp/src/resources.py
|
|
|
|
from mcp.server import Server
|
|
from mcp.types import Resource, ResourceTemplate
|
|
import asyncpg
|
|
|
|
server = Server("dexorder-user")
|
|
|
|
@server.list_resources()
|
|
async def list_resources() -> list[Resource]:
|
|
return [
|
|
Resource(
|
|
uri="context://user-profile",
|
|
name="User Profile",
|
|
description="Trading style, preferences, and background",
|
|
mimeType="text/plain",
|
|
),
|
|
Resource(
|
|
uri="context://conversation-summary",
|
|
name="Conversation Summary",
|
|
description="Recent conversation with RAG-enhanced context",
|
|
mimeType="text/plain",
|
|
),
|
|
Resource(
|
|
uri="context://workspace-state",
|
|
name="Workspace State",
|
|
description="Current chart, watchlist, positions",
|
|
mimeType="application/json",
|
|
),
|
|
Resource(
|
|
uri="context://system-prompt",
|
|
name="Custom System Prompt",
|
|
description="User's custom AI instructions",
|
|
mimeType="text/plain",
|
|
),
|
|
]
|
|
|
|
@server.read_resource()
|
|
async def read_resource(uri: str) -> str:
|
|
if uri == "context://user-profile":
|
|
return await build_user_profile()
|
|
elif uri == "context://conversation-summary":
|
|
return await build_conversation_summary()
|
|
elif uri == "context://workspace-state":
|
|
return await build_workspace_state()
|
|
elif uri == "context://system-prompt":
|
|
return await get_custom_prompt()
|
|
else:
|
|
raise ValueError(f"Unknown resource: {uri}")
|
|
```
|
|
|
|
### RAG Integration
|
|
|
|
```python
|
|
# user-mcp/src/rag.py
|
|
|
|
import chromadb
|
|
from sentence_transformers import SentenceTransformer
|
|
|
|
class ConversationRAG:
|
|
def __init__(self, db_path: str):
|
|
self.chroma = chromadb.PersistentClient(path=db_path)
|
|
self.collection = self.chroma.get_or_create_collection("conversations")
|
|
self.embedder = SentenceTransformer('all-MiniLM-L6-v2')
|
|
|
|
async def search_conversation_history(
|
|
self,
|
|
query: str,
|
|
limit: int = 5,
|
|
min_score: float = 0.7
|
|
) -> list[dict]:
|
|
"""Semantic search over conversation history"""
|
|
# Embed query
|
|
query_embedding = self.embedder.encode(query).tolist()
|
|
|
|
# Search
|
|
results = self.collection.query(
|
|
query_embeddings=[query_embedding],
|
|
n_results=limit,
|
|
)
|
|
|
|
# Filter by score and format
|
|
relevant = []
|
|
for i, score in enumerate(results['distances'][0]):
|
|
if score >= min_score:
|
|
relevant.append({
|
|
'content': results['documents'][0][i],
|
|
'metadata': results['metadatas'][0][i],
|
|
'score': score,
|
|
})
|
|
|
|
return relevant
|
|
|
|
async def add_message(self, message_id: str, role: str, content: str, metadata: dict):
|
|
"""Add message to RAG index"""
|
|
embedding = self.embedder.encode(content).tolist()
|
|
|
|
self.collection.add(
|
|
ids=[message_id],
|
|
embeddings=[embedding],
|
|
documents=[content],
|
|
metadatas=[{
|
|
'role': role,
|
|
'timestamp': metadata.get('timestamp'),
|
|
**metadata
|
|
}]
|
|
)
|
|
```
|
|
|
|
### Conversation Summary Builder
|
|
|
|
```python
|
|
# user-mcp/src/context.py
|
|
|
|
async def build_conversation_summary(user_id: str) -> str:
|
|
"""Build conversation summary with RAG"""
|
|
# 1. Get recent messages
|
|
recent_messages = await db.get_messages(
|
|
user_id=user_id,
|
|
limit=50,
|
|
order='desc'
|
|
)
|
|
|
|
# 2. Get current focus (last user message)
|
|
last_user_msg = next(
|
|
(m for m in recent_messages if m.role == 'user'),
|
|
None
|
|
)
|
|
|
|
if not last_user_msg:
|
|
return "No recent conversation history."
|
|
|
|
# 3. RAG search for relevant context
|
|
rag = ConversationRAG(f"/data/users/{user_id}/rag")
|
|
relevant_context = await rag.search_conversation_history(
|
|
query=last_user_msg.content,
|
|
limit=5,
|
|
min_score=0.7
|
|
)
|
|
|
|
# 4. Build summary
|
|
summary = f"Recent Conversation Summary:\n\n"
|
|
|
|
# Recent messages (last 10)
|
|
summary += "Last 10 messages:\n"
|
|
for msg in recent_messages[-10:]:
|
|
summary += f"- {msg.role}: {msg.content[:100]}...\n"
|
|
|
|
# Relevant past context
|
|
if relevant_context:
|
|
summary += "\nRelevant past discussions (RAG):\n"
|
|
for ctx in relevant_context:
|
|
timestamp = ctx['metadata'].get('timestamp', 'unknown')
|
|
summary += f"- [{timestamp}] {ctx['content'][:150]}...\n"
|
|
|
|
# Inferred focus
|
|
summary += f"\nCurrent focus: {infer_topic(last_user_msg.content)}\n"
|
|
|
|
return summary
|
|
|
|
def infer_topic(message: str) -> str:
|
|
"""Simple topic extraction"""
|
|
keywords = {
|
|
'strategy': ['strategy', 'backtest', 'trading system'],
|
|
'indicator': ['indicator', 'rsi', 'macd', 'moving average'],
|
|
'analysis': ['analyze', 'chart', 'price action'],
|
|
'risk': ['risk', 'position size', 'stop loss'],
|
|
}
|
|
|
|
message_lower = message.lower()
|
|
for topic, words in keywords.items():
|
|
if any(word in message_lower for word in words):
|
|
return topic
|
|
|
|
return 'general trading discussion'
|
|
```
|
|
|
|
---
|
|
|
|
## Benefits of This Architecture
|
|
|
|
1. **Privacy**: Conversation history never leaves user's container
|
|
2. **Customization**: Each user controls their RAG, embeddings, prompt engineering
|
|
3. **Scalability**: Platform harness is stateless - horizontally scalable
|
|
4. **Cost Control**: Platform pays for Claude, users pay for their compute/storage
|
|
5. **Portability**: Users can export/migrate their entire context
|
|
6. **Development**: Users can test prompts/context locally without platform involvement
|
|
|
|
---
|
|
|
|
## Future Enhancements
|
|
|
|
### Dynamic Resource URIs
|
|
|
|
Support parameterized resources:
|
|
```
|
|
context://conversation/{session_id}
|
|
context://strategy/{strategy_name}
|
|
context://backtest/{backtest_id}/results
|
|
```
|
|
|
|
### Resource Templates
|
|
|
|
MCP supports resource templates for dynamic discovery:
|
|
```python
|
|
@server.list_resource_templates()
|
|
async def list_templates() -> list[ResourceTemplate]:
|
|
return [
|
|
ResourceTemplate(
|
|
uriTemplate="context://strategy/{name}",
|
|
name="Strategy Context",
|
|
description="Context for specific strategy",
|
|
)
|
|
]
|
|
```
|
|
|
|
### Streaming Resources
|
|
|
|
For large context (e.g., full backtest results), support streaming:
|
|
```python
|
|
@server.read_resource()
|
|
async def read_resource(uri: str) -> AsyncIterator[str]:
|
|
if uri.startswith("context://backtest/"):
|
|
async for chunk in stream_backtest_results(uri):
|
|
yield chunk
|
|
```
|
|
|
|
---
|
|
|
|
## Migration Path
|
|
|
|
For users with existing conversation history in platform DB:
|
|
|
|
1. **Export script**: Migrate platform history → user container DB
|
|
2. **RAG indexing**: Embed all historical messages into ChromaDB
|
|
3. **Preference migration**: Copy user preferences to container
|
|
4. **Cutover**: Switch to resource-based context fetching
|
|
|
|
Platform can keep read-only archive for compliance, but active context lives in user container.
|