mcp-integration ยท diff
v2.0.0 to v2.0.0
44 added, 3 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
version: "2.0.0"
- globs: src/mcp/**/*.ts
- description: MCP server integration patterns and conventions
+ globs: "src/mcp/**/*.ts"
+ alwaysApply: true
+ description: "MCP server integration patterns and conventions"
lastUpdated: "2025-10-08"
- dependencies: ["quality-standards", "database-patterns", "api-patterns"]
+ dependencies: ["quality-standards", "database-patterns", "api-patterns", "bun-runtime"]
---
# MCP Integration Rules
+ ## ๐ Code Searchability Patterns
+
+ ### Find mcp-integration Issues with ast-grep
+
+ ```bash
+ # Find export async function $NAME(params: $PARAMS, env: Env)
+ # Find MCPToolResult
+ # Find registerTool($$$)
+ # Find JSON-RPC
+ ast-grep --pattern 'export async function $NAME(params: $PARAMS, env: Env)' src/
+ ast-grep --pattern 'MCPToolResult' src/
+ ast-grep --pattern 'registerTool($$$)' src/
+ ast-grep --pattern 'JSON-RPC' src/
+ sg -p 'export' src/
+ sg -p 'MCPToolResult' src/
+ sg -p 'registerTool($$$)' src/
+ sg -p 'JSON-RPC' src/
+ ```
+
+ ### mcp-integration Discovery Commands
+
+ ```bash
+ sg search "MCPToolResult" src/
+ sg search "registerTool" src/
+ sg search "JSON-RPC" src/
+ sg search "export async function" src/mcp/
+ ```
+
+ ### Search Examples
+
+ ```bash
+ # Find MCP tool handlers
+ sg search 'export' src/
+ # Find tool registration
+ sg search 'MCPToolResult' src/
+ # Find JSON-RPC usage
+ sg search 'registerTool($$$)' src/
+ # Find MCP result types
+ sg search 'JSON-RPC' src/
+ ```
## Overview
The MCP (Model Context Protocol) server provides **13 working tools** via JSON-RPC 2.0 endpoint at `/mcp`.
See [docs/MCP_INTEGRATION_STATUS.md](mdc:docs/MCP_INTEGRATION_STATUS.md) for complete status.
## Architecture
```
src/mcp/
โโโ server.ts # JSON-RPC 2.0 request router
โโโ types.ts # MCP protocol types
โโโ tools.ts # Tool definitions and schemas
โโโ toolRegistry.ts # Handler registry
โโโ handlers/ # Tool implementations (9 handlers)
โโโ steamMoves.ts
โโโ riskConcentration.ts
โโโ sharpActivity.ts
โโโ timeSeriesCLV.ts
โโโ enhancedSharpScore.ts
โโโ holdForecast.ts
โโโ handleAndHold.ts
โโโ customerVolume.ts
โโโ timeSeriesAnalytics.ts
```
## Request Flow
```
POST /mcp โ handleMCPRequest() [server.ts]
โ
Route by method:
- initialize โ Return capabilities
- tools/list โ Return tool definitions
- tools/call โ callTool() [toolRegistry.ts]
โ
Handler Function [handlers/*.ts]
โ
D1 Database Query
โ
MCPToolResult โ JSON-RPC Response
```
## Adding a New Tool
### 1. Create Handler (`src/mcp/handlers/myTool.ts`)
```typescript
import type { MCPToolResult, MCPEnv } from '../types';
import { normalizeD1Result } from '../../utils/request';
interface MyToolArgs {
param1: string;
param2?: number;
}
interface TableRow {
id: string;
field: string;
// ... other fields
}
export async function getMyTool(
args: MyToolArgs,
env: MCPEnv
): Promise<MCPToolResult> {
// Validate args
if (!args.param1) {
return {
content: [{ type: 'text', text: 'Error: param1 required' }],
isError: true
};
}
// Query database
const result = await env.ANALYTICS.prepare(
'SELECT * FROM table WHERE field = ?'
).bind(args.param1).all();
// Normalize D1 results
const data = normalizeD1Result<TableRow>(result);
// Return formatted result
return {
content: [{
type: 'text',
text: JSON.stringify(data, null, 2)
}]
};
}
```
### 2. Register in `toolRegistry.ts`
```typescript
import { getMyTool } from './handlers/myTool';
case 'getMyTool':
return await getMyTool(args, env);
```
### 3. Define in `tools.ts`
```typescript
{
name: 'getMyTool',
description: 'Clear description of what this tool does',
inputSchema: {
type: 'object',
properties: {
param1: { type: 'string', description: '...' },
param2: { type: 'number', description: '...', optional: true }
},
required: ['param1']
}
}
```
## Testing MCP Tools
### Direct Handler Testing (Fastest)
```bash
bun scripts/test-handlers-direct.ts
```
### HTTP Testing
```bash
# Start server
bun run dev
# Test endpoint
curl -X POST http://localhost:8787/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
## Database Tables
MCP tools use these D1 tables:
- `sharp_indicators` - Customer profiling
- `line_movements` - Line changes
- `bet_history` - Historical bets โจ NEW
- `hold_tracking` - Hold % history โจ NEW
- `exposure_tracking` - Real-time exposure
See [migrations/0003_mcp_tables.sql](mdc:migrations/0003_mcp_tables.sql) for MCP-specific schema.
## Tool Categories
### Intelligence (4 tools)
- getBettingExposure, getCLV, getHoldPercentage, getSharpScore
### Live Betting (3 tools)
- getSteamMoves, getRiskConcentration, getSharpActivity
### Analytics (6 tools)
- getTimeSeriesCLV, getEnhancedSharpScore, getHoldForecast
- getHandleAndHold, getCustomerVolume, getTimeSeriesAnalytics
## Best Practices
1. **Error Handling:** Always return `isError: true` for failures
2. **Validation:** Validate all args before database queries
3. **Type Safety:** Use TypeScript interfaces for args
4. **Performance:** Optimize queries (target < 500ms)
5. **Documentation:** Clear descriptions in tool definitions
6. **Testing:** Test with direct handler script first
7. **D1 Normalization:** Always use `normalizeD1Result()` for type safety โญ **NEW**
---
## Related Rules
- [Quality Standards](mdc:.cursor/rules/quality-standards.mdc) - Code quality standards โญ **NEW**
- [Database Patterns](mdc:.cursor/rules/database-patterns.mdc) - Database best practices
- [API Patterns](mdc:.cursor/rules/api-patterns.mdc) - API design patterns
- [Cloudflare Workers](mdc:.cursor/rules/cloudflare-workers.mdc) - Workers patterns
## Related Documentation
- [docs/QUALITY_STANDARDS.md](mdc:docs/QUALITY_STANDARDS.md) - Complete quality guide โญ **NEW**
- [src/utils/request.ts](mdc:src/utils/request.ts) - Request & D1 utilities โญ **NEW**
- [docs/MCP_TESTING_GUIDE.md](mdc:docs/MCP_TESTING_GUIDE.md) - Testing guide
- [docs/MCP_ENDPOINTS.md](mdc:docs/MCP_ENDPOINTS.md) - Complete API reference
- [src/mcp/](mdc:src/mcp/) - MCP server implementation
---
**Status:** Production-ready MCP server
**Last Updated:** 2025-10-08