Skip to content

PLANS.md

Latest commit

 

History

History
138 lines (95 loc) · 6.17 KB

PLANS.md

File metadata and controls

138 lines (95 loc) · 6.17 KB
Raw

Ensembl MCP Server - Improvement Plans

Plans 1-6 (caching, batch operations, response truncation, error handling, structured logging, retry logic), Plan 7 (Vitest), Plan 8 (MCP resources & prompts), Plan 9 (input validation), Plan 10 (GRCh37 support), Plan 12 (CI/CD), and Plan 13 (pagination) have been implemented. The plans below cover the next round of improvements.

Plan 7: Proper Test Framework (Vitest) (Implemented)

Migrated to Vitest with @vitest/coverage-v8. Deleted custom test runner and 12 integration test files. Created vitest.config.ts, migrated input-normalizer.test.ts and input-validator.test.ts to Vitest syntax, and added new unit tests for cache.ts, error-handler.ts, response-processor.ts, and formatter.ts. 152 tests across 6 files, all passing. Scripts: npm test, npm run test:watch, npm run test:coverage.

Plan 8: MCP Resources and Prompts (Implemented)

Implemented in eb43ce2. Added src/handlers/resources.ts (species, releases, assembly, biotypes), src/handlers/prompts.ts (analyze-variant, compare-orthologs, region-survey, gene-report), and wired into index.ts with full MCP resource/prompt protocol support.

Plan 9: Input Validation Before API Calls (Implemented)

Implemented with src/utils/species-data.ts (shared species constants), src/utils/input-validator.ts (8 validators + batch + tool-aware dispatcher for all 10 tools), wired into src/handlers/tools.ts, and tests/input-validator.test.ts (77 tests). Also deduplicated species data from error-handler.ts and input-normalizer.ts.

Plan 10: GRCh37 Support via Dedicated Server (Implemented)

Implemented with dynamic server routing based on assembly argument. Added resolveBaseUrl(), getServerIdentifier(), checkGrch37Support() to src/utils/species-data.ts. Cache keys include server prefix for isolation. Per-server release version tracking via Map<string, string>. All 15+ API methods and 7 batch methods thread baseUrl through. Assembly parameter added to 8 tool schemas. validateAssembly() added to input validator. Unsupported GRCh37 endpoints (homology, genetree, cafe, alignment) fail fast with clear error. 187 tests across 7 files, all passing.

Plan 11: Observability and Diagnostics Tool

Problem

No runtime visibility into server health, cache effectiveness, or API performance. When users experience slowness or errors, there's no way to diagnose without reading raw logs.

Approach

Add an ensembl_diagnostics tool that exposes internal metrics and a health check.

New Tool: ensembl_diagnostics

Parameters:

  • check_type: "health" | "cache_stats" | "api_stats" | "full"

Returns:

{
  "health": {
    "ensembl_api": "reachable",
    "ping_ms": 145,
    "current_release": 114,
    "server_version": "15.0"
  },
  "cache": {
    "entries": 247,
    "max_entries": 1000,
    "hit_rate": "73.2%",
    "hits": 891,
    "misses": 326,
    "evictions": 12,
    "memory_estimate_kb": 1240
  },
  "api": {
    "total_requests": 1217,
    "errors": 14,
    "retries": 8,
    "avg_response_ms": 312,
    "rate_limit_waits": 45
  }
}

Files to Modify

Modify: src/utils/cache.ts

  • Add getStats(): CacheStats method tracking hits, misses, evictions

Modify: src/utils/ensembl-api.ts

  • Add request counters: totalRequests, errors, retries, responseTimes[]
  • Add getStats(): ApiStats method
  • Add healthCheck(): Promise<HealthStatus> -- calls /info/ping and /info/data

Modify: src/handlers/tools.ts

  • Add ensembl_diagnostics tool definition and handler

Size Estimate

~50 lines for stats tracking, ~40 lines for the tool definition/handler.

Plan 12: CI/CD Pipeline (Implemented)

Added .github/workflows/ci.yml with three parallel jobs: typecheck (tsc --noEmit), unit tests (vitest run --coverage with coverage artifact upload), and Docker build verification. Triggers on push to main and pull requests.

Plan 13: Pagination for Large Result Sets (Implemented)

Added page and page_size parameters to 5 tools (ensembl_feature_overlap, ensembl_regulatory, ensembl_meta, ensembl_compara, ensembl_variation). Extended ProcessOptions and ProcessedResponse.metadata with pagination fields (page, page_size, total_pages, has_next). Updated truncateArray to support offset-based slicing. page_size supersedes max_results when both provided. Out-of-range pages return empty data with correct metadata. Backward-compatible — omitting pagination params produces identical output. Added validatePagination to input validator, wired into all 5 tool validators. 220 tests across 7 files, all passing.

Plan 14: Streaming for Large Responses

Problem

Large FASTA sequences and 200-item batch results get truncated at a hard limit. MCP supports streaming content, which would let clients receive data incrementally instead of losing it.

Approach

Use MCP's streaming capabilities for tools that can return large payloads.

Candidates for Streaming

  • ensembl_sequence -- FASTA output for long sequences or batch requests
  • ensembl_compara -- large gene tree results
  • Batch operations -- 200-item results

Files to Modify

Modify: src/handlers/tools.ts

  • For qualifying responses, use MCP's StreamableHTTPServerTransport or chunked text content
  • Fall back to truncation for clients that don't support streaming

Size Estimate

~80 lines. Depends on MCP SDK streaming support maturity.

Priority Order

Priority Plan Impact Effort
1 Plan 7: Vitest migration High (enables all other testing) Done
2 Plan 8: MCP Resources & Prompts High (new capabilities) Done
3 Plan 9: Input validation High (faster failures, less API load) Done
4 Plan 12: CI/CD High (quality gate) Done
5 Plan 10: GRCh37 support Medium (unlocks hg19 users) Done
6 Plan 11: Diagnostics tool Medium (operational visibility) Low
7 Plan 13: Pagination Medium (better data access) Done
8 Plan 14: Streaming Low (nice-to-have) Medium