_index.yaml

version: "1.0"
namespace: code_tools

entries:
  - name: definition
    kind: ns.definition
    readme: file://README.md
    meta:
      title: Code Analysis Tools
      description: MCP tools for Tree-sitter code analysis — parse, query, extract symbols and diagnose syntax errors

  - name: dependency.mcp
    kind: ns.dependency
    component: butschster/mcp-server
    version: ">=0.1.0"

  # ===========================================================================
  # Shared Libraries
  # ===========================================================================

  - name: parser_lib
    kind: library.lua
    source: file://parser_lib.lua
    modules:
      - fs
      - registry
      - treesitter
      - json

  - name: queries_lib
    kind: library.lua
    source: file://queries_lib.lua

  # ===========================================================================
  # Tools
  # ===========================================================================

  # --- code_languages: list supported languages ---

  - name: code_languages
    kind: function.lua
    source: file://code_languages.lua
    method: call
    modules:
      - treesitter
    imports:
      parser: code_tools:parser_lib
      queries: code_tools:queries_lib
    meta:
      mcp.tool: true
      mcp.name: "code_languages"
      mcp.description: "List all supported programming languages for code analysis tools, including file extension mappings and available query patterns."
      mcp.inputSchema:
        type: "object"
      mcp.annotations:
        readOnlyHint: true

  # --- code_parse: syntax tree ---

  - name: code_parse
    kind: function.lua
    source: file://code_parse.lua
    method: call
    modules:
      - json
      - treesitter
    imports:
      parser: code_tools:parser_lib
    meta:
      mcp.tool: true
      mcp.name: "code_parse"
      mcp.description: "Parse source code into a syntax tree (AST) and display its structure. Supports all Tree-sitter languages. Provide code directly or read from a project file."
      mcp.inputSchema:
        type: "object"
        properties:
          code:
            type: "string"
            description: "Source code to parse. Either 'code'+'language' or 'path' is required."
          language:
            type: "string"
            description: "Programming language (e.g. 'go', 'python', 'javascript'). Required with 'code', auto-detected with 'path'."
          path:
            type: "string"
            description: "File path relative to project root. Language is auto-detected from extension."
          project:
            type: "string"
            description: "Project identifier (optional, uses default project)."
          depth:
            type: "integer"
            description: "Maximum tree depth to display (default: 3, max: 20)."
            minimum: 0
            maximum: 20
      mcp.annotations:
        readOnlyHint: true

  # --- code_outline: structural overview ---

  - name: code_outline
    kind: function.lua
    source: file://code_outline.lua
    method: call
    modules:
      - json
      - treesitter
    imports:
      parser: code_tools:parser_lib
      queries: code_tools:queries_lib
    meta:
      mcp.tool: true
      mcp.name: "code_outline"
      mcp.description: "Generate a structural outline of source code showing functions, types/classes, imports, and variables with line numbers. Uses language-specific query patterns for accurate extraction."
      mcp.inputSchema:
        type: "object"
        properties:
          code:
            type: "string"
            description: "Source code to analyze. Either 'code'+'language' or 'path' is required."
          language:
            type: "string"
            description: "Programming language (e.g. 'go', 'python', 'lua'). Required with 'code', auto-detected with 'path'."
          path:
            type: "string"
            description: "File path relative to project root. Language is auto-detected from extension."
          project:
            type: "string"
            description: "Project identifier (optional, uses default project)."
      mcp.annotations:
        readOnlyHint: true

  # --- code_symbols: flat symbol list ---

  - name: code_symbols
    kind: function.lua
    source: file://code_symbols.lua
    method: call
    modules:
      - json
      - treesitter
    imports:
      parser: code_tools:parser_lib
      queries: code_tools:queries_lib
    meta:
      mcp.tool: true
      mcp.name: "code_symbols"
      mcp.description: "Extract all symbols (functions, types, imports, variables) from source code as a flat searchable list. Supports filtering by symbol kind and name pattern."
      mcp.inputSchema:
        type: "object"
        properties:
          code:
            type: "string"
            description: "Source code to analyze. Either 'code'+'language' or 'path' is required."
          language:
            type: "string"
            description: "Programming language. Required with 'code', auto-detected with 'path'."
          path:
            type: "string"
            description: "File path relative to project root."
          project:
            type: "string"
            description: "Project identifier (optional)."
          kind:
            type: "string"
            description: "Filter by symbol kind: 'function', 'type', 'import', 'variable', 'export'."
            enum:
              - "function"
              - "type"
              - "import"
              - "variable"
              - "export"
          filter:
            type: "string"
            description: "Filter symbols by name pattern (Lua pattern match)."
      mcp.annotations:
        readOnlyHint: true

  # --- code_query: custom Tree-sitter queries ---

  - name: code_query
    kind: function.lua
    source: file://code_query.lua
    method: call
    modules:
      - json
      - treesitter
    imports:
      parser: code_tools:parser_lib
    meta:
      mcp.tool: true
      mcp.name: "code_query"
      mcp.description: "Run a custom Tree-sitter S-expression query against source code. Returns all captures with name, position, and text. Useful for advanced pattern matching like finding all error handling blocks, specific function calls, or structural patterns."
      mcp.inputSchema:
        type: "object"
        properties:
          query:
            type: "string"
            description: "Tree-sitter query in S-expression syntax, e.g. '(function_declaration name: (identifier) @name)'"
          code:
            type: "string"
            description: "Source code to query. Either 'code'+'language' or 'path' is required."
          language:
            type: "string"
            description: "Programming language. Required with 'code', auto-detected with 'path'."
          path:
            type: "string"
            description: "File path relative to project root."
          project:
            type: "string"
            description: "Project identifier (optional)."
          limit:
            type: "integer"
            description: "Maximum captures to return (default: 100, max: 500)."
            minimum: 1
            maximum: 500
        required:
          - "query"
      mcp.annotations:
        readOnlyHint: true

  # --- code_diagnostics: syntax error detection ---

  - name: code_diagnostics
    kind: function.lua
    source: file://code_diagnostics.lua
    method: call
    modules:
      - json
      - treesitter
    imports:
      parser: code_tools:parser_lib
    meta:
      mcp.tool: true
      mcp.name: "code_diagnostics"
      mcp.description: "Check source code for syntax errors using Tree-sitter. Reports error locations, missing tokens, and surrounding context. Works even with partially broken code (Tree-sitter is error-tolerant)."
      mcp.inputSchema:
        type: "object"
        properties:
          code:
            type: "string"
            description: "Source code to check. Either 'code'+'language' or 'path' is required."
          language:
            type: "string"
            description: "Programming language. Required with 'code', auto-detected with 'path'."
          path:
            type: "string"
            description: "File path relative to project root."
          project:
            type: "string"
            description: "Project identifier (optional)."
          limit:
            type: "integer"
            description: "Maximum errors to report (default: 50, max: 200)."
            minimum: 1
            maximum: 200
      mcp.annotations:
        readOnlyHint: true