server-implementation-fix.md•5.97 kB
# MCP Server Implementation Fix
## Problem
The initial implementation of the MCP filesystem server was using the low-level `Server` class from `@modelcontextprotocol/sdk/server/index.js`, which does not directly support the high-level tool registration method `tool()`. This caused TypeScript compilation errors as the `Server` class does not expose methods for registering tools in the same way as the high-level API.
## Root Cause
The issue stemmed from using the wrong class from the MCP SDK:
```typescript
// Original problematic import
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
```
The `Server` class is a low-level implementation that requires using `setRequestHandler` for handling different types of requests. This makes the implementation more verbose and error-prone.
## Solution
We fixed the issue by using the high-level `McpServer` class instead, which provides a more developer-friendly API:
```typescript
// Fixed import
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
```
The `McpServer` class provides:
- A simplified API for registering tools using the `tool()` method
- Better TypeScript type inference
- More intuitive resource and prompt registration
- Express-like API design
## Implementation Changes
1. Changed the server instantiation from `Server` to `McpServer`
2. Kept the tool implementations the same, as they were already following the correct pattern
3. No changes were needed to the tool implementations themselves, as they were already structured correctly
## Benefits of the Fix
- Cleaner code through the high-level API
- Better TypeScript support
- Simplified tool registration
- More maintainable codebase
- Follows MCP SDK best practices
## Lessons Learned
When implementing MCP servers:
1. Use the high-level `McpServer` class for most implementations
2. Only use the low-level `Server` class when you need custom protocol handling
3. Follow the examples from the SDK documentation for best practices
4. The MCP SDK provides different abstraction levels - choose the right one for your use case
## References
- MCP SDK Documentation
- Quick Start Guide example using `McpServer`
- TypeScript implementation guidelines
## Testing Implementation
### Testing Challenges and Solutions
#### 1. Tool Handler Testing
Initially, we attempted to test the MCP tools by directly accessing the tool handlers through `server.tool()`. This approach failed because:
- The `server.tool()` method doesn't return the handler function
- We needed to properly type the handlers according to MCP SDK specifications
**Solution:**
- Defined handlers separately from registration
- Added proper TypeScript types for MCP content responses
- Included the required `extra` parameter in handler signatures
```typescript
const readFileHandler = async ({ path: filePath }: { path: string }, extra: any) => {
const content = await fs.readFile(filePath, 'utf-8');
return { content: [{ type: 'text' as const, text: content }] };
};
```
#### 2. ES Modules and Jest Configuration
We encountered issues with Jest not properly handling ES modules and TypeScript:
- TypeScript compilation errors in test files
- Jest not recognizing ES module imports
- Warning about hybrid module resolution
**Solution:**
1. Updated Jest configuration to support ES modules:
```javascript
export default {
preset: 'ts-jest',
testEnvironment: 'node',
extensionsToTreatAsEsm: ['.ts'],
moduleNameMapper: {
'^(\\.{1,2}/.*)\\.js$': '$1',
},
transform: {
'^.+\\.tsx?$': ['ts-jest', { useESM: true }],
}
}
```
2. Modified package.json to use experimental VM modules:
```json
{
"scripts": {
"test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
}
}
```
#### 3. Type Safety in MCP Responses
The MCP SDK expects specific response types for tool handlers. We had to ensure:
- Correct content type signatures
- Proper use of const assertions for type literals
- Handling of the extra parameter in tool handlers
**Solution:**
- Used TypeScript's const assertion to ensure literal types
- Properly typed the content array elements
- Added handler signatures matching the SDK's expectations
### Test Coverage
The test suite now covers the core filesystem operations:
1. File Reading
- Success cases with existing files
- Error handling for non-existent files
2. File Writing
- Creating new files
- Writing content
- Success confirmation
3. Directory Operations
- Listing directory contents
- Distinguishing between files and directories
- Proper formatting of listings
4. File Movement
- Moving files between locations
- Validation of source/destination
- Success/failure cases
5. File Search
- Pattern-based search
- Case-insensitive matching
- Results formatting
### Best Practices Established
1. **Isolation**: Each test creates and cleans up its own test files
2. **Temporary Directories**: Using `os.tmpdir()` for test file storage
3. **Cleanup**: Proper cleanup in `afterAll` and `beforeEach` hooks
4. **Type Safety**: Strict TypeScript typing for all handlers
5. **Error Handling**: Testing both success and error cases
6. **Async/Await**: Proper handling of asynchronous operations
### Future Improvements
1. Add more edge cases to existing tests
2. Implement test coverage reporting
3. Add integration tests with actual MCP client
4. Mock filesystem for faster tests
5. Add stress testing for large files/directories
## Benefits of the Testing Implementation
- Ensures reliability of filesystem operations
- Catches type-related issues early
- Provides examples of proper tool usage
- Maintains codebase quality
- Facilitates future changes and refactoring
## Lessons Learned
1. Always test handlers with proper MCP response types
2. Configure build tools properly for ES modules
3. Use TypeScript's type system to ensure SDK compliance
4. Maintain clean test isolation
5. Properly handle asynchronous operations in tests