fledgling: Instructions file for Claude Code

Fledgling: Project Conventions

Architecture

SQL macros first, MCP tools second. Every tool is backed by a reusable macro in sql/<tier>.sql. The tool publication in sql/tools/<tier>.sql is a thin wrapper using mcp_publish_tool(). Never put business logic in tool publications.

SQL Macro Files (sql/<tier>.sql)

File header

-- Fledgling: <Tier Name> Macros (<extension_name>)
--
-- Brief description of what this tier provides.

Per-macro comments

Every macro gets a block comment with: name, description, and examples.

-- macro_name: What it does in one line.
-- Additional context if needed.
--
-- Examples:
--   SELECT * FROM macro_name('arg1');
--   SELECT * FROM macro_name('arg1', 'arg2');
CREATE OR REPLACE MACRO macro_name(...) AS TABLE
    ...

Naming

• Macro names: snake_case (SQL convention)
• Column aliases: snake_case
• Use AS TABLE for all macros that return result sets
• Use := for optional parameters with defaults
• Avoid parameter names that shadow column names in the query body (use qualified t.column references or rename the parameter)

Tool Publication Files (sql/tools/<tier>.sql)

File header

-- Fledgling: <Tier Name> Tool Publications
--
-- MCP tool publications for <description>.
-- Wraps macros from sql/<tier>.sql.

mcp_publish_tool() call pattern

Always pass all 6 arguments:

SELECT mcp_publish_tool(
    'ToolName',                    -- 1. PascalCase tool name
    'Description for the agent.',  -- 2. Tool description
    'SELECT * FROM macro(...)',    -- 3. SQL template
    '{...}',                       -- 4. JSON Schema properties
    '["required_param"]',          -- 5. Required params list
    'markdown'                     -- 6. Output format (always 'markdown')
);

Optional parameter handling (duckdb_mcp#19 workaround)

MCP tool params arrive as strings. Omitted params must be sent as the literal string 'null' by the test harness. Tool templates convert them back: