feat: Implement Extended Data Types MCP Server

[jbdevprimary]

Migrated from jbdevprimary/extended-data-types#61

---

Summary

Create an MCP (Model Context Protocol) server that provides natural language API documentation and usage guidance for all extended-data-types utilities. This server will function similarly to Context7, but specifically for the extended-data-types library, enabling AI agents to discover and effectively use the 90+ functions in this library.

Background

Extended-data-types provides a comprehensive utility library with:

• Serialization: YAML (with custom tags), JSON (via orjson), TOML, HCL2
• File Operations: Path resolution, Git repository detection, encoding detection, read/write
• Data Structures: Deep merging, flattening, filtering for maps and lists
• String Transformations: Case conversion (snake_case, camelCase, kebab-case), pluralization, humanization
• Type Utilities: Safe type conversion, special type handling, validation
• Export Utilities: Format-aware data export with GitHub Actions syntax escaping

The Kiro spec at .kiro/specs/ecosystem-foundation/ outlines this as a core component of the ecosystem foundation.

MCP Server Design

Tools to Implement

Following the Context7 pattern, the MCP server should expose these tools:

1. resolve-function-id

Resolves a function name or description to the exact extended-data-types function.

Input:

• query (string): Function name or description to search for

Output:

• List of matching functions with:
  • Function name
  • Module path
  • Category
  • Brief description
  • Parameter count

2. get-function-docs

Fetches comprehensive documentation for a specific function.

Input:

• functionName (string): Exact function name from __all__ exports
• includeExamples (boolean, optional): Include usage examples from tests

Output:

• Function signature with full type annotations
• Docstring with Args, Returns, Raises
• Usage examples extracted from test cases
• Related functions in same category

Function Categories

Organize functions into these categories for discovery:

Category	Functions	Count
Serialization	encode_yaml, decode_yaml, encode_json, decode_json, encode_toml, decode_toml, decode_hcl2, base64_encode, base64_decode	9
File Operations	read_file, write_file, decode_file, delete_file, resolve_local_path, get_encoding_for_file_path, match_file_extensions, file_path_depth, file_path_rel_to_root, is_url	10
Git Integration	get_parent_repository, get_repository_name, get_tld, clone_repository_to_temp	4
String Transformations	to_snake_case, to_camel_case, to_kebab_case, to_pascal_case, humanize, pluralize, singularize, titleize, ordinalize	9
String Utilities	bytestostr, lower_first_char, upper_first_char, removeprefix, removesuffix, sanitize_key, titleize_name, truncate	8
Map Operations	deep_merge, flatten_map, filter_map, deduplicate_map, unhump_map, zipmap, all_values_from_map, first_non_empty_value_from_map, get_default_dict, create_merger	10
List Operations	filter_list, flatten_list, split_list_by_type, split_dict_by_type	4
State Utilities	is_nothing, are_nothing, any_non_empty, all_non_empty, all_non_empty_in_dict, all_non_empty_in_list, first_non_empty, yield_non_empty	8
Type Utilities	typeof, strtobool, strtoint, strtofloat, strtodate, strtodatetime, strtotime, strtopath, convert_special_type, convert_special_types, reconstruct_special_type, reconstruct_special_types, make_hashable, get_default_value_for_type, get_primitive_type_for_instance_type	15
Matcher Utilities	is_non_empty_match, is_partial_match	2
Stack Utilities	get_caller, get_available_methods, filter_methods, get_inputs_from_docstring, get_unique_signature, update_docstring	6
Export/Import	make_raw_data_export_safe, wrap_raw_data_for_export, unwrap_raw_data_from_import	3
Data Types	FilePath, SortedDefaultDict	2

Total: 90 functions/classes

Implementation Tasks

Phase 1: Core Infrastructure

• Create src/extended_data_types/mcp_server/ module structure
• Implement ExtendedDataTypesMCPServer class with stdio protocol
• Add function introspection using inspect module on __all__ exports
• Implement docstring parsing for structured documentation extraction

Phase 2: Tool Implementation

• Implement resolve-function-id tool with fuzzy matching
• Implement get-function-docs tool with full documentation
• Add category-based function organization
• Extract usage examples from 302 test cases

Phase 3: Distribution

• Add MCP server as optional dependency group
• Create CLI entry point: edt-mcp or extended-data-types-mcp
• Support both stdio and HTTP transport modes
• Add MCP configuration templates for various AI tools

Phase 4: Documentation

• Update README with MCP server usage
• Add configuration examples for Claude, Cursor, VS Code, etc.
• Create API reference for MCP tools

Technical Requirements

Dependencies

[project.optional-dependencies]
mcp = [
    "mcp>=1.0.0",  # Model Context Protocol SDK
]

Entry Point

[project.scripts]
edt-mcp = "extended_data_types.mcp_server:main"

Configuration Example

{
  "mcpServers": {
    "extended-data-types": {
      "command": "uvx",
      "args": ["--from", "extended-data-types[mcp]", "edt-mcp"]
    }
  }
}

Success Criteria

1. MCP server starts in < 2 seconds
2. Function lookup responds in < 100ms
3. All 90 functions are documented and discoverable
4. Usage examples extracted from test suite
5. Works with Claude, Cursor, VS Code, and other MCP clients

Related

• Kiro spec: .kiro/specs/ecosystem-foundation/
• Context7 reference: https://github.com/upstash/context7
• MCP SDK: https://modelcontextprotocol.io/

[jbdevprimary]

Triage Assessment

This issue tracks the MCP Server feature - a component of the larger Ecosystem Foundation initiative.

Status

• ✅ Specification complete ()
• 📋 Detailed design provided
• 🎯 Target: Post-1.0 feature development

Recommendation

This is a future enhancement, not a blocker for 1.0 stable release. Keeping open for tracking, but this represents new functionality beyond the current stable utility library.

The current package (v5.3.1) provides comprehensive data type utilities without requiring MCP server capabilities for core functionality.

---

Triaged by agent during 1.0 stabilization assessment

[jbdevprimary]

Status Update — 2026-02-24

The MCP Server component has been implemented and is functional:

Implemented

• mcp_server_main() entry point exported from extended_data_types
• get_library_functions() — extracts 90+ functions from __all__ with full categorization
• resolve_function_id tool — resolves function names to documentation
• get_function_docs tool — retrieves docstrings and signatures
• Function categorization into 13 categories (Serialization, File Ops, Git, Strings, Maps, Lists, State, Types, etc.)
• Full test suite: 5 MCP server tests passing
• Property test: MCP doc completeness verification against __all__

Remaining Work

• Usage example extraction from test cases (302 tests)
• PyPI publishing as standalone MCP server package
• MCP configuration documentation
• Performance optimization (startup < 2s target)

See PR #72 for the implementation merge and Issue #1 for the broader ecosystem foundation progress.