Skip to main content
Glama
teaguesterling

Fledgling

by teaguesterling
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Fledgling

MCP tools that help AI agents get their bearings in a codebase — unified SQL views over code, git, docs, and conversations, powered by DuckDB.

Two ways to run:

# Zero-dependency MCP server (pure DuckDB, no Python)
curl -sL https://raw.githubusercontent.com/teaguesterling/fledgling/main/sql/install-fledgling.sql | duckdb

# Python API
pip install fledgling-mcp
python -c "import fledgling; fledgling.connect().find_definitions('**/*.py').show()"

Before and After

Your agent wastes tokens parsing text. Fledgling gives it purpose-built tools that return structured data.

Find a function definition

Before — grep returns raw text the agent has to parse:

grep -rn 'def parse_config' src/
src/config.py:42:def parse_config(path: str, strict: bool = False) -> Config:

After — the agent calls FindDefinitions:

FindDefinitions(file_pattern="src/**/*.py", name_pattern="parse_config%")

| file_path     | name         | kind                | start_line | end_line | signature                                   |
|---------------|--------------|---------------------|------------|----------|---------------------------------------------|
| src/config.py | parse_config | DEFINITION_FUNCTION | 42         | 68       | def parse_config(path: str, strict: ...) -> |

View code by CSS selector

SelectCode(source="src/**/*.py", selector=".func#parse_config")

Returns markdown with # file:range headings and fenced code blocks — full source bodies, not just signatures.

Compose queries across domains

-- Functions in recently changed files, ranked by cyclomatic complexity
SELECT * FROM changed_function_summary('HEAD~3', 'HEAD', 'src/**/*.py')

Code analysis + git history in one call. No shell pipelines, no string parsing.

Related MCP server: CodeGraph

What's Included

MCP Tools (24)

Tool

What it does

ReadLines

Read file lines with range, context, and match filtering

FindDefinitions

AST-based search for functions/classes across 30 languages

FindCode

CSS selector search: .func, #name, :has(...), ::callers

ViewCode

View source matched by CSS selector with context lines

SelectCode

Render selector matches as markdown: headings + full source blocks

CodeStructure

Structural overview with cyclomatic complexity metrics

ExploreProject

First-contact briefing: languages, structure, docs, recent activity

InvestigateSymbol

Deep dive: definitions, callers, and call sites for a symbol

ReviewChanges

Change review: affected files and functions ranked by complexity

SearchProject

Multi-source search across definitions, calls, and docs

MDOverview

Browse all docs with keyword/regex search

MDSection

Read a specific markdown section by ID

GitDiffSummary

File-level change summary between revisions

GitDiffFile

Line-level unified diff

GitShow

File content at a specific git revision

Help

Built-in skill guide with workflows and macro catalog

ChatSessions

Browse Claude Code conversation sessions

ChatSearch

Full-text search across conversation messages

ChatToolUsage

Tool usage patterns

ChatDetail

Deep view of a single session

SearchContent

BM25 full-text search across all indexed content

SearchDocs

BM25 search over markdown sections

SearchCode

BM25 search over code (definitions, comments, strings)

FtsStats

Index diagnostics: row and file counts per extractor/kind

Plus 30+ composable SQL macros via the query tool: explore_query, investigate_query, review_query, search_query, pss_render, find_class_members, complexity_hotspots, function_callers, module_dependencies, structural_diff, doc_outline, search_content, search_docs, search_code, find_code_ranked, and more.

Python API

import fledgling

# Create a connection with all macros loaded
con = fledgling.connect()

# Macros as methods — return composable DuckDB Relations
con.find_definitions("**/*.py", name_pattern="parse%").show()
con.recent_changes(5).select("hash, message").df()
con.code_structure("src/**/*.py").filter("cyclomatic_complexity > 5").show()

# Attach to an existing DuckDB connection
import duckdb
raw = duckdb.connect("my.db")
con = fledgling.attach(raw, root="/my/project")

# Compose your own init sequence
raw = duckdb.connect()
fledgling.load_extensions(raw)
fledgling.set_session_root(raw, root="/my/project")
fledgling.load_macros(raw, modules=["sandbox", "source", "code"])
# ... do custom setup ...
fledgling.lockdown(raw, allowed_dirs=["/my/project"])

# Module-level for quick scripting
from fledgling.tools import find_definitions, recent_changes
find_definitions("**/*.py").show()

CLI for Humans

fledgling find-definitions 'src/**/*.py' '%parse%'
fledgling recent-changes 10 -c hash,message
fledgling CodeStructure '**/*.rs' -f csv
fledgling query "SELECT * FROM complexity_hotspots('**/*.py', 10)"
fledgling help
fledgling update   # preserves your module/profile config

Tab completion: eval "$(fledgling --completions bash)"

Install

Per-project (recommended)

curl -sL https://raw.githubusercontent.com/teaguesterling/fledgling/main/sql/install-fledgling.sql | duckdb

Creates .fledgling-init.sql, .fledgling-help.md, and .mcp.json in your project root. Customize modules and profile on the install page.

Via pip

pip install fledgling-mcp

Requirements

  • DuckDB 1.5.2, pinned (duckdb==1.5.2) — CLI for the MCP server, Python package for the API. The community extensions are built per DuckDB version, so 1.5.3 can't find them and FTS breaks; stay on 1.5.2.

  • Community extensions installed automatically

Ecosystem

Fledgling is the SQL macro foundation. Two companion packages build on it:

Package

What it does

Install

pluckit

Fluent Python API — CSS selectors over ASTs, jQuery-style chaining, code mutations

pip install ast-pluckit

squackit

MCP server with smart defaults, caching, workflows, prompts, and session state

pip install squackit (coming soon)

Architecture

┌─────────────────────────────────────────┐
│  squackit (FastMCP)                     │  pip install squackit
│  Smart defaults, caching, workflows,    │
│  prompts, kibitzer, resources           │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │  pluckit (fluent Python API)      │  │  pip install ast-pluckit
│  │  CSS selectors, jQuery-style      │  │
│  │  chaining, code mutations         │  │
│  │                                   │  │
│  │  ┌─────────────────────────────┐  │  │
│  │  │  fledgling (SQL + Python)   │  │  │  pip install fledgling-mcp
│  │  │  24 MCP tools, 30+ macros   │  │  │  or: curl | duckdb
│  │  │  fledgling.connect()        │  │  │
│  │  │  read_lines, sitting_duck,  │  │  │
│  │  │  duck_tails, markdown       │  │  │
│  │  └─────────────────────────────┘  │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

Dependencies flow strictly downward. Fledgling has no dependency on pluckit or squackit. Pluckit has an optional soft-dep on fledgling. Squackit depends on pluckit.

Development

git clone https://github.com/teaguesterling/fledgling.git
cd fledgling
pip install -e .
pip install duckdb pytest
pytest

539 tests across SQL macros, MCP integration, CLI, Python API, and e2e integration.

Coming Soon

  • fledgling-edit — AST-aware code editing with pattern matching and template substitution

  • Kit management — Quartermaster pattern: curated tool subsets per task type with model-aware configuration

Why "Fledgling"?

From the 1996 film Fly Away Home — a girl raises orphaned geese and teaches them their migration route by leading them with an ultralight aircraft. The geese imprint on her, learn the path, and eventually fly it on their own.

Fledgling gives AI agents structured tools so they can learn to navigate your codebase. A fledgling is a young bird learning to fly. This tool is what gets it airborne.

License

Apache-2.0

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
19dResponse time
2wRelease cycle
6Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/teaguesterling/fledgling'

If you have feedback or need assistance with the MCP directory API, please join our Discord server