# Code Mode Compatibility Changes
## Summary
This document summarizes the changes made to the entrez-mcp-server to improve Code Mode compatibility by returning structured JSON data instead of emoji-formatted text, standardizing parameter names, and improving error messages.
## Changes Made
### 1. Structured JSON Response Support
**File: `/src/lib/response-formatter.ts`**
- Added new interface `SearchStructuredResult` for structured search responses
- Added new method `formatSearchStructured()` that returns:
```typescript
{
count: number,
retmax: number,
retstart: number,
idlist: string[],
queryTranslation?: string,
webEnv?: string,
queryKey?: string,
warnings?: string[],
suggestions?: string[]
}
```
- This format is directly usable by LLMs in Code Mode without text parsing
### 2. Format Parameter for Response Control
**File: `/src/tools/consolidated-entrez.ts`**
- Added `format` parameter to `entrez_query` tool schema:
- `format: "structured"` (default) - Returns JSON data suitable for programmatic use
- `format: "human"` - Returns emoji-formatted text for human readability
- Updated `handleSearch()` method to:
- Return structured JSON by default using `ResponseFormatter.formatSearchStructured()`
- Include all search metadata in a machine-readable format
- Provide minimal text summary alongside structured data
- Maintain backward compatibility with `format: "human"` option
### 3. Parameter Name Standardization
**File: `/src/tools/esearch.ts`**
- Changed primary parameter from `db` to `database` (more descriptive)
- Added backward compatibility by accepting both `db` and `database` parameters
- Updated handler to support: `const dbName = database || db || "pubmed"`
- Marked `db` as deprecated in parameter description
**Note:** The main `entrez_query` tool in `consolidated-entrez.ts` already used `database` parameter, so it was already consistent.
### 4. Improved Error Messages (Code Mode Friendly)
**Files: `/src/tools/consolidated-entrez.ts`, `/src/tools/consolidated-data.ts`**
Removed emojis from error messages and contextual help to make them parseable:
**Before:**
```typescript
'🔍 Search Tips: Use keywords like "cancer treatment"'
'🆔 ID Format: Use comma-separated numeric UIDs'
'💡 Suggestion: Try broader keywords'
```
**After:**
```typescript
'Search Tips: Use keywords like "cancer treatment"'
'ID Format: Use comma-separated numeric UIDs'
'Suggestion: Try broader keywords'
```
Changes made to error handling in:
- Query validation suggestions
- Operation-specific contextual help (search, summary, fetch, link operations)
- General error messages in both `entrez_query` and `entrez_data` tools
## Benefits
### For Code Mode / LLMs
1. **Direct Data Access**: No more regex parsing of emoji-formatted text
```javascript
// Before: Required text parsing
const idMatch = searchText.match(/🆔 \*\*IDs\*\*: ([0-9, ]+)/);
const ids = idMatch[1].split(', ');
// After: Direct access
const ids = result.idlist;
const count = result.count;
```
2. **Structured Metadata**: All search information is in typed fields
- `count`, `retmax`, `retstart`, `idlist` are directly accessible
- `warnings` and `suggestions` are in arrays
- `queryTranslation` shows how NCBI interpreted the query
3. **Parseable Errors**: Error messages no longer contain emojis that might confuse parsing logic
### Backward Compatibility
- All existing functionality is preserved
- Human-readable format still available via `format: "human"` parameter
- Default format changed to `structured` (Code Mode friendly)
- Parameter `db` still works alongside new `database` parameter
## Migration Guide
### For Code Mode Users
Use the structured format (default):
```javascript
const result = await helpers.entrez.invoke('entrez_query', {
operation: 'search',
database: 'pubmed',
term: 'brain cancer',
retmax: 10
});
// Direct access to results
const totalResults = result.count;
const ids = result.idlist;
const suggestions = result.suggestions || [];
```
### For Human-Readable Output
Explicitly request human format:
```javascript
const result = await helpers.entrez.invoke('entrez_query', {
operation: 'search',
database: 'pubmed',
term: 'brain cancer',
retmax: 10,
format: 'human' // Get emoji-formatted text
});
```
## Testing
Build completed successfully with no errors:
```bash
npm run build
# Output: Total Upload: 3721.82 KiB / gzip: 734.25 KiB
```
## Breaking Changes
**None** - All changes are backward compatible:
- Default format changed from emoji text to structured JSON, but human format still available
- Parameter `database` is preferred, but `db` still works
- Error messages no longer have emojis, but content is the same
## Recommendations for Testing
1. Test search operations with structured format:
- Verify `count`, `retmax`, `idlist` fields are populated
- Check that `warnings` and `suggestions` arrays work correctly
- Ensure `queryTranslation` is included when available
2. Test backward compatibility:
- Use `format: "human"` and verify emoji formatting still works
- Use `db` parameter and verify it still works
3. Test error handling:
- Verify validation errors have clear messages without emojis
- Check that contextual help is still useful
## Future Enhancements
Consider applying similar changes to:
1. Summary operations (`entrez_summary`) - return structured metadata
2. Fetch operations (`entrez_fetch`) - return structured article data
3. Other E-utilities operations
## References
- Original issue: Code Mode servers should return structured JSON
- Recommendation document: `/docs/code-mode-server-recommendations.md`
- Implementation follows MCP specification for tool responses
