# Datai FastMCP TypeScript Server - Implementation Checklist
## Project Overview
- [ ] **Project Goal**: Build high-performance FastMCP TypeScript server for Datai blockchain endpoints
- [ ] **Location**: `/Users/ilessio/dev-agents/PARTNERS/DATAI/datai-mcp/src/`
- [ ] **API Key**: `dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS`
- [ ] **Target**: 8 endpoints (4 DeFi + 4 Balance tools)
## FastMCP Rules Activation Checklist
- [ ] `@fastMCP_ts-core.mdc` - Core server implementation
- [ ] `@fastMCP_ts-tools.mdc` - Tool implementation patterns
- [ ] `@fastMCP_ts-logging.mdc` - Logging standards
- [ ] `@fastMCP_ts-errors.mdc` - Error handling
- [ ] `@fastMCP_ts-testing.mdc` - Testing approaches
- [ ] `@fastMCP_ts-session.mdc` - Session management
- [ ] `@fastMCP_ts-content.mdc` - Content formatting
- [ ] `@fastMCP_ts-cli.mdc` - CLI tools
- [ ] `@fastMCP_ts-resources.mdc` - Resource management
## Phase 1: Project Setup (30 min) ⏱️ ✅
### Project Structure
- [x] Create main project directory structure
- [x] Set up `/src/config/` directory
- [x] Set up `/src/tools/` directory
- [x] Set up `/src/utils/` directory
- [x] Set up `/src/types/` directory
- [x] Set up `/src/tests/` directory
### Package Configuration
- [x] Initialize `package.json` with proper metadata
- [x] Configure `tsconfig.json` with strict TypeScript settings
- [x] Install FastMCP dependencies: `fastmcp`
- [x] Install validation: `zod`
- [x] Install HTTP client: `axios`
- [x] Install TypeScript types: `@types/node`
- [x] Set up build and dev scripts
### Initial Files
- [x] Create `src/index.ts` (main entry point)
- [x] Create `src/config/constants.ts` (API endpoints)
- [x] Create `src/config/types.ts` (base interfaces)
## Phase 2: Core Infrastructure (45 min) ✅
### API Client Setup
- [x] Create `src/utils/api-client.ts`
- [x] Implement Datai client class with authentication
- [x] Configure 180-second timeout
- [x] Set up proper headers (Authorization, User-Agent)
- [x] Implement request/response interceptors
### Logging System
- [x] Create `src/utils/logger.ts` following `@fastMCP_ts-logging.mdc`
- [x] Implement FastMCP logging standards
- [x] Set up debug, info, warn, error levels
- [x] Configure structured logging with context
- [x] Add request/response logging
### Validation & Error Handling
- [x] Create `src/utils/validation.ts` with Zod schemas
- [x] Create `src/utils/error-handler.ts` following `@fastMCP_ts-errors.mdc`
- [x] Implement wallet address validation
- [x] Implement chain parameter validation
- [x] Create custom error classes for API failures
### Type Definitions
- [x] Create `src/types/api-responses.ts` for API response interfaces
- [x] Create `src/types/tool-params.ts` for tool parameter interfaces
- [x] Create `src/types/index.ts` for type exports
## Phase 3: Tool Implementation (60 min) ✅
### Individual Tool Files (8 separate files)
- [x] **Tool 1**: `get_all_user_defi_positions`
- [x] Create `src/tools/get-all-user-defi-positions.ts` file
- [x] Implement createGetAllUserDeFiPositionsTool function following `@fastMCP_ts-tools.mdc`
- [x] Add Zod schema for wallet parameter
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/userDeFiPositions/all/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"`
- [x] **Tool 2**: `get_user_defi_positions_by_chain`
- [x] Create `src/tools/get-user-defi-positions-by-chain.ts` file
- [x] Implement createGetUserDeFiPositionsByChainTool function
- [x] Add Zod schema for wallet + chain parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/userDeFiPositions/0x09CF915e195aF33FA7B932C253352Ae9FBdB0106?chain=arb"`
- [x] **Tool 3**: `get_user_defi_positions_by_multiple_chains`
- [x] Create `src/tools/get-user-defi-positions-by-multiple-chains.ts` file
- [x] Implement createGetUserDeFiPositionsByMultipleChainsTool function
- [x] Add Zod schema for wallet + chains parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/userDeFiPositionsByChains/0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50?chains=avax,arb"`
- [x] **Tool 4**: `get_user_defi_positions_by_protocol`
- [x] Create `src/tools/get-user-defi-positions-by-protocol.ts` file
- [x] Implement createGetUserDeFiPositionsByProtocolTool function
- [x] Add Zod schema for wallet + protocol parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/userDeFiPositions/0x09CF915e195aF33FA7B932C253352Ae9FBdB0106?protocol=uniswap"`
- [x] **Tool 5**: `get_user_defi_protocol_balances_by_chain`
- [x] Create `src/tools/get-user-defi-protocol-balances-by-chain.ts` file
- [x] Implement createGetUserDeFiProtocolBalancesByChainTool function
- [x] Add Zod schema for wallet + chain parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/balances/defi/0x09CF915e195aF33FA7B932C253352Ae9FBdB0106?chain=arb"`
- [x] **Tool 6**: `get_user_overall_balance_all_chains`
- [x] Create `src/tools/get-user-overall-balance-all-chains.ts` file
- [x] Implement createGetUserOverallBalanceAllChainsTool function
- [x] Add Zod schema for wallet parameter
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/balances/all/0x09CF915e195aF33FA7B932C253352Ae9FBdB0106"`
- [x] **Tool 7**: `get_user_overall_balance_by_chain`
- [x] Create `src/tools/get-user-defi-positions-by-chain.ts` file
- [x] Implement createGetUserOverallBalanceByChainTool function
- [x] Add Zod schema for wallet + chain parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/balances/overall/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=eth"`
- [x] **Tool 8**: `get_wallet_balances_by_chain`
- [x] Create `src/tools/get-wallet-balances-by-chain.ts` file
- [x] Implement createGetWalletBalancesByChainTool function
- [x] Add Zod schema for wallet + chain parameters
- [x] Add comprehensive logging
- [ ] Test with: `curl -H "Authorization: dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS" "https://api-v1.mymerlin.io/api/merlin/public/balances/token/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045?chain=base"`
### Tool Organization
- [x] Create `src/tools/index.ts` for tool exports and registration
- [x] Implement registerAllTools function that registers all 8 individual tools
- [x] Export all individual tool creator functions for testing
## Phase 4: Server Setup (30 min) ⏳ READY TO START
### Main Server Configuration
- [ ] Implement main FastMCP server in `src/index.ts` following `@fastMCP_ts-core.mdc`
- [ ] Configure server metadata (name, version, description)
- [ ] Set up FastMCP logging configuration
- [ ] Enable health checks
- [ ] Configure ping for connection health
### Transport Configuration
- [ ] Configure STDIO transport for local development
- [ ] Configure SSE transport for remote access
- [ ] Configure HTTP Stream transport option
- [ ] Add environment variable support for transport selection
### Session Management
- [ ] Implement session event handlers following `@fastMCP_ts-session.mdc`
- [ ] Add connect event logging
- [ ] Add disconnect event logging
- [ ] Add error event handling
### Tool Registration
- [ ] Register all 4 DeFi position tools
- [ ] Register all 4 balance tools
- [ ] Verify tool registration with proper names and descriptions
## Phase 5: Testing (45 min) ⏱️
### Unit Tests
- [ ] Create `src/tests/utils/` directory
- [ ] Test API client functionality following `@fastMCP_ts-testing.mdc`
- [ ] Test validation schemas
- [ ] Test error handling utilities
- [ ] Test logging functionality
### Tool Tests
- [ ] Create `src/tests/tools/` directory
- [ ] Create individual test files for each tool:
- [ ] `test-get-all-user-defi-positions.ts`
- [ ] `test-get-user-defi-positions-by-chain.ts`
- [ ] `test-get-user-defi-positions-by-multiple-chains.ts`
- [ ] `test-get-user-defi-positions-by-protocol.ts`
- [ ] `test-get-user-defi-protocol-balances-by-chain.ts`
- [ ] `test-get-user-overall-balance-all-chains.ts`
- [ ] `test-get-user-overall-balance-by-chain.ts`
- [ ] `test-get-wallet-balances-by-chain.ts`
- [ ] Test parameter validation for all tools
- [ ] Test error scenarios for all tools
### Integration Tests (Real API Data - No Mocking)
- [ ] Create `src/tests/integration/` directory
- [ ] **Strategy**: Use real Datai API with actual endpoints (no mocking)
- [ ] **API Key**: Will be passed via `DATAI_API_KEY` environment variable in client JSON configuration
- [ ] **Test Data**: Use exact same parameters from working curl commands for consistency
- [ ] Test real API endpoints with test wallet addresses:
- [ ] Test with `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`
- [ ] Test with `0x09CF915e195aF33FA7B932C253352Ae9FBdB0106`
- [ ] Test with `0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50`
- [ ] Validate response formats match expected schemas
- [ ] Test timeout handling (180 seconds)
- [ ] Test authentication with provided API key
- [ ] **Exact Parameter Testing**: Use same parameters as curl commands:
- [ ] `chain=arb` for Arbitrum tests
- [ ] `chains=avax,arb` for multiple chain tests
- [ ] `protocol=uniswap` for protocol tests
- [ ] `chain=eth` for Ethereum tests
- [ ] `chain=base` for Base tests
### FastMCP CLI Testing
- [ ] Test with `npx fastmcp dev src/index.ts`
- [ ] Test with `npx fastmcp inspect src/index.ts`
- [ ] Validate STDIO transport functionality
- [ ] Validate SSE transport functionality
### Manual Endpoint Testing
- [ ] Test all 8 curl commands manually
- [ ] Verify all endpoints return expected data
- [ ] Confirm proper error handling for invalid parameters
- [ ] Test with all 3 test wallet addresses
## Phase 6: Documentation (30 min) ⏱️
### README Documentation
- [ ] Create comprehensive `README.md`
- [ ] Document installation instructions
- [ ] Document configuration options
- [ ] Document all 8 tools with examples
- [ ] Add usage examples for each tool
### Configuration Guide
- [ ] Document API key setup
- [ ] Document transport configuration
- [ ] Document environment variables
- [ ] Add troubleshooting section
### Deployment Guide
- [ ] Document build process
- [ ] Document deployment options
- [ ] Add performance considerations
- [ ] Include monitoring recommendations
## Final Validation Checklist
### Functionality
- [ ] All 8 tools working with real API endpoints
- [ ] Proper parameter validation for all tools
- [ ] Comprehensive error handling
- [ ] Full TypeScript type safety
### Transport Support
- [ ] STDIO transport working
- [ ] SSE transport working
- [ ] HTTP Stream transport working
- [ ] Proper transport selection via environment
### Quality Assurance
- [ ] Comprehensive logging throughout
- [ ] User-friendly error messages
- [ ] Proper timeout handling
- [ ] Clean code structure
### Production Readiness
- [ ] All tests passing
- [ ] Documentation complete
- [ ] Performance validated
- [ ] Ready for NPM publication
## Test Wallet Addresses (Reference)
- **WALLET1**: `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`
- **WALLET2**: `0x09CF915e195aF33FA7B932C253352Ae9FBdB0106`
- **WALLET3**: `0xbdfa4f4492dd7b7cf211209c4791af8d52bf5c50`
## API Configuration (Reference)
- **Base URL**: `https://api-v1.mymerlin.io`
- **API Key**: `dbNb54fQUGCuy2xO3RXPRw7bH9nbDSkS`
- **Timeout**: 180 seconds
- **Auth Header**: `Authorization: {API_KEY}`
---
**Progress Tracking**: ⏱️ = Time estimate | ✅ = Completed | ❌ = Failed | 🔄 = In Progress
**Total Estimated Time**: 4 hours (240 minutes)
**Current Phase**: Not Started
**Completion**: 0/8 tools implemented
