@chain-lens/mcp-tool

Implements the Model Context Protocol (MCP) server specification to expose ChainLens functionality as a standardized tool interface compatible with Claude Desktop and other MCP-compliant clients. Uses MCP's request-response messaging pattern to translate client tool calls into ChainLens API operations, handling schema validation, error mapping, and response serialization across the protocol boundary.

Exposes ChainLens seller discovery as an MCP tool that accepts filter parameters (location, capabilities, reputation metrics) and returns paginated seller profiles. Implements query parameter validation, result ranking/sorting, and structured response formatting compatible with MCP's tool result schema, allowing agents to programmatically search and evaluate data providers.

Provides an MCP tool for submitting data requests to discovered sellers and retrieving request status/results. Implements request creation (with seller ID, data schema, pricing negotiation), asynchronous job tracking (polling or webhook-based status updates), and result retrieval. Handles request state transitions (pending, accepted, processing, completed, failed) and integrates with ChainLens's job queue system.

Implements a dedicated MCP tool for checking the status of submitted data requests and retrieving completed results. Polls ChainLens's job queue system using request IDs, returns structured status objects (state, progress percentage, error messages), and handles result deserialization when jobs complete. Supports both synchronous polling (blocking until completion) and asynchronous status checks (return current state without waiting).

Defines and validates the JSON Schema for all exposed ChainLens tools (seller discovery, data requests, job status), ensuring that Claude and MCP clients can introspect available operations, required parameters, and response formats. Implements schema validation on incoming requests and outgoing responses, providing clear error messages for malformed inputs. Handles type coercion (string to number, array flattening) and default parameter injection.

Implements a unified error handling layer that translates ChainLens API errors (rate limits, authentication failures, seller unavailable) into MCP-compliant error responses with consistent structure. Maps HTTP status codes to MCP error codes, enriches errors with retry guidance (Retry-After headers, exponential backoff recommendations), and normalizes all responses (success and failure) into MCP's standard JSON-RPC format with proper error objects.

Manages ChainLens API credentials (API keys, tokens) securely within the MCP server process, handling credential injection into outgoing requests, token refresh logic, and credential rotation. Supports multiple authentication methods (API key, OAuth2 bearer token) and implements credential caching to avoid repeated lookups. Provides secure credential storage patterns (environment variables, credential files with restricted permissions) and logs authentication failures without exposing secrets.

Provides structured logging of all MCP tool invocations, ChainLens API calls, and responses, enabling debugging and monitoring. Logs include request parameters (sanitized of sensitive data), response status, execution time, and error details. Implements observability hooks (timing instrumentation, error counters) compatible with standard logging frameworks (Winston, Pino) and monitoring systems (Prometheus, DataDog). Supports log level configuration (debug, info, warn, error) for production vs. development environments.