mcp-ts-core Framework

The @cyanheads/mcp-ts-core/utils module provides a suite of Tier 3 parsers for common data formats. These parsers are lazy-loaded on first call to minimize initial bundle size.

Common Behaviors

• Async by default: All methods are async unless explicitly noted as synchronous.
• Automatic <think> stripping: Parsers automatically strip <think>...</think> blocks from the start of input and log them at debug level (except dateParser and pdfParser).
• Optional Context: The context? parameter is optional and accepts either a Context handler or a RequestContext bag.
• Input Budgets: Parsers are unbounded by default. To prevent memory issues, pass maxBytes to reject inputs exceeding the limit. This throws a ValidationError with reason: 'parser_input_too_large'. Use DEFAULT_TEXT_PARSER_MAX_BYTES (1 MiB) or DEFAULT_BINARY_PARSER_MAX_BYTES (25 MiB) as reference values.
• Error Handling: Errors throw McpError. The error message follows the pattern <summary>: <library message>. The data field contains { reason }, while the original stack and input sample are preserved on the cause property.

import { yamlParser, xmlParser, csvParser, jsonParser, pdfParser, dateParser, frontmatterParser } from '@cyanheads/mcp-ts-core/utils';

The Model Context Protocol is a modular system designed to enable rich interactions between clients and servers. It is composed of several layers:

• Base Protocol: Core JSON-RPC message types.
• Versioning and Compatibility: Mechanisms for protocol version and extension negotiation.
• Message Patterns: Supported patterns like request/response, multi-round-trip requests (MRTR), and subscribe/notify.
• Authorization: An authentication and authorization framework (primarily for HTTP-based transports).
• Server Features: Capabilities exposed by servers, such as Resources, Prompts, and Tools.
• Client Features: Capabilities provided by clients, such as Elicitation, Sampling, and Root directory lists.
• Utilities: Cross-cutting concerns like logging and argument completion.

All implementations MUST support the base protocol, versioning, and the core message patterns.

Overview

DataCanvas is a Tier 3 analytical workspace for tabular MCP servers, backed by DuckDB. While IStorageProvider is for key/value blob storage, DataCanvas provides an analytical surface to register tabular data from upstream APIs, run SQL queries across multiple tables, and export results (CSV, Parquet, or JSON).

When to use DataCanvas

Use DataCanvas only when both of the following conditions are met:

1. The data is analytical, not just large: The data should be suitable for SQL operations like SELECT ... GROUP BY, joins, or time-series filtering. If the workflow is simply finding a record via metadata (titles, IDs), use standard MCP list filtering instead. The decision is based on shape, not just row count.
2. The data is too big to inline: If a result set is small (e.g., $\le \sim 100$ rows of compact data), inline it in the tool response. Use DataCanvas as the third option for larger, complex tabular datasets.

Critical Requirement

If a tool emits a canvas_id, that server must also provide a dataframe_query tool. Without a query tool, the canvas_id is unusable by an agent.

Streamable HTTP is an MCP transport where the server operates as an independent process handling multiple client connections via a single HTTP endpoint (the MCP endpoint) that accepts POST requests.

Key characteristics:

• Request Model: Every JSON-RPC request or notification from the client is sent as its own individual HTTP POST.
• Response Model: The server responds to each request with either a single JSON object (application/json) or a Server-Sent Events (SSE) stream (text/event-stream) scoped specifically to that request.
• Notifications: Request-scoped notifications (like progress) are sent via the SSE response stream. Long-lived change notifications (like resource updates) are delivered via a dedicated long-lived stream obtained through a subscriptions/listen request.
• Server-to-Client Interactions: Interactions like sampling or elicitation use the Multi Round-Trip Requests (MRTR) pattern, where the server returns an InputRequiredResult containing input requests, and the client retries the original request with the necessary inputResponses.

MCP uses JSON Schema for validation. Implementations must adhere to the following dialect rules:

1. Default Dialect: If a schema does not include a $schema field, it defaults to JSON Schema 2020-12. Clients and servers MUST support this.
2. Explicit Dialect: Schemas MAY include a $schema field to specify a different dialect (e.g., draft-07).
3. Validation Requirements:
   • Implementations MUST validate schemas according to their declared or default dialect.
   • Implementations MUST handle unsupported dialects gracefully by returning an error indicating the dialect is not supported.
   • Implementations SHOULD document which additional dialects they support.

#### Default dialect (2020-12):
```json
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Explicit dialect (draft-07):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}