apitomy-data-models-mcp: Instructions file for Claude Code

Project Guidelines

Overview

This is an MCP (Model Context Protocol) server that wraps the @apitomy/data-models library to provide AI-assisted querying, editing, validation, and transformation of OpenAPI and AsyncAPI documents. It is a TypeScript project using the @modelcontextprotocol/sdk.

Architecture

Source Layout

src/
  index.ts              # Entry point (stdio transport)
  server.ts             # MCP server creation and tool/resource registration
  session-manager.ts    # In-memory session store (Map<string, SessionEntry>)
  tools/
    session.ts          # Session lifecycle tools (create, list, get, close, export)
    query.ts            # Document query tools (info, paths, schemas, nodes, operations)
    edit.ts             # Document editing tools (set, remove, add schema)
    transform.ts        # Format conversion tools (JSON/YAML, version conversion)
    validation.ts       # Document validation tool
  resources/
    document.ts         # MCP resource templates (info, paths, schemas per session)
  visitors/
    index.ts            # Barrel export for all visitors
    DocumentInfoVisitor.ts
    OperationCollectorVisitor.ts
    PathCollectorVisitor.ts
    SchemaCollectorVisitor.ts
    SchemaContainerVisitor.ts
    SecuritySchemeCollectorVisitor.ts
    ServerCollectorVisitor.ts
    TagCollectorVisitor.ts
    ClearNodeVisitor.ts
    RemoveNodeVisitor.ts
  util/
    errors.ts           # Error result helpers
    format.ts           # JSON/YAML format detection and serialization
    model-type-map.ts   # ModelType string-to-enum mapping

Session Model

Documents are managed through named sessions stored in a singleton SessionManager. Each session holds a parsed Document object from the data-models library, along with metadata (model type, file path, format, timestamps). Tools receive a session_name parameter to identify which document to operate on.

Tool Categories

• Session tools (7): document_load, document_create, document_save, document_close, document_list_sessions, document_export, document_clone_session
• Query tools (16): document_get_info, document_list_paths, document_get_operation, document_list_schemas, document_get_node, document_list_operations, document_get_schema, document_list_security_schemes, document_list_servers, document_list_tags, document_list_parameters, document_list_responses, document_list_media_types, document_list_extensions, document_list_examples, document_find_refs
• Edit tools (76): document_set_info, document_add_path, document_add_schema, document_set_node, document_remove_node, document_add_operation, document_remove_operation, document_add_response, document_add_parameter, document_add_request_body, document_add_media_type, document_set_media_type_schema, document_add_security_scheme, document_remove_response, document_add_response_definition, document_remove_parameter, document_remove_security_scheme, document_add_tag, document_add_server, document_set_contact, document_set_license, document_remove_schema, document_remove_path, document_add_channel, document_add_response_header, document_remove_request_body, document_update_security_scheme, document_remove_tag, document_rename_tag, document_remove_server, document_add_extension, document_remove_extension, document_remove_response_header, document_add_schema_property, document_remove_schema_property, document_add_security_requirement, document_add_example, document_set_operation_info, document_set_operation_tags, document_set_schema_required, document_set_schema_type, document_add_schema_enum, document_remove_all_security_requirements, document_remove_media_type, document_add_parameter_definition, document_remove_parameter_definition, document_add_header_definition, document_remove_header_definition, document_add_example_definition, document_remove_example_definition, document_add_request_body_definition, document_remove_request_body_definition, document_delete_contact, document_delete_license, document_update_extension, document_remove_all_examples, document_rename_path, document_rename_schema, document_copy_operation, document_move_operation, document_add_callback, document_remove_callback, document_add_link, document_remove_link, document_set_external_docs, document_add_server_variable, document_remove_server_variable, document_remove_all_operations, document_remove_all_responses, document_remove_all_parameters, document_remove_all_response_headers, document_remove_all_schema_properties, document_remove_all_servers, document_remove_all_tags, document_remove_all_security_schemes, document_remove_all_extensions
• Validation tool (1): document_validate
• Transform tools (2): document_transform, document_dereference