[v1.1.3] Hotfix: Annotation Evaluation and CLI Smoke Tests

v1.1.3

Fixed

• Prevented NameError during tool/resource registration by eagerly evaluating type annotations.
• Updated raster band statistics to use stats() with safe fallback handling.

Added

• Regression tests ensuring resource/tool annotations are evaluated (guards against missing typing imports).
• CI CLI smoke test via gdal --help.

Notes

• This is a hotfix release on top of 1.1.2. Tagged as v1.1.3.

v1.1.1 - Domain Transcendence

v1.0.1 - "Conversational Guidance"

Release Date: October 26, 2025
Type: Patch Release

Overview

A focused refinement of the reflection system's tone and posture, shifting from prescriptive blocking to conversational advisory guidance.

What Changed

Reflection Prompt Philosophy:

• Before: "Before reprojecting, you must justify..." (prescriptive, blocking)
• After: "The operation will use... [guidance provided]" (advisory, educational)

All four reflection prompts updated to respect user autonomy while maintaining educational value:

• CRS Selection - Conversational guidance about projection choices
• Resampling Methods - Advisory explanations for method selection
• Hydrology Conditioning - Prepared for future tool integration
• Aggregation Strategy - Prepared for future tool integration

Why This Matters

The system now acts as a helpful colleague rather than a gatekeeper. When the AI detects a potentially suboptimal choice, it:

• ✅ Asks conversational questions instead of blocking
• ✅ Provides educational context
• ✅ Respects explicit user requirements
• ✅ Documents reasoning without artificial friction

Technical Details

• No API changes - fully backward compatible
• Same tools and capabilities
• Prompt refinement only
• Full type safety maintained
• All tests passing

Philosophy Alignment

This patch implements the core principle: "Preserve agent autonomy while amplifying expertise." The epistemic accountability remains, but the delivery respects that users know their requirements.

Documented in: ADR-0026 Amendment

---

v1.1.1 - "Domain Transcendence"

Release Date: October 26, 2025
Type: Major Feature Release

Overview

Achieves vector/raster tool parity and validates the groundbreaking architectural principle: methodological reasoning transcends data types. Cross-domain reflection cache sharing enables 75% cache hit rates in multi-operation workflows.

🎉 Major Features

1. Complete Vector Tool Suite (6 Tools)

New Tools:

• vector_reproject - CRS transformation with cross-domain reflection
• vector_convert - Format migration (Shapefile ↔ GeoPackage ↔ GeoJSON) with encoding control
• vector_clip - Spatial subsetting by bounding box or mask geometry
• vector_buffer - Proximity analysis with configurable resolution
• vector_simplify - Geometry simplification (Douglas-Peucker/Visvalingam algorithms)
• vector_info - Enhanced metadata inspection (already existed, now part of suite)

Coverage: ~1,350 lines of production-quality code

• Full type safety (mypy strict mode)
• Pydantic models throughout
• ADR compliance (0012, 0013, 0017)
• Comprehensive error handling

2. Cross-Domain Reflection Architecture (The Innovation)

The Breakthrough:
A CRS justification for EPSG:3857 is about the projection's properties (conformal, web-optimized, distortion tradeoffs) - not whether you're reprojecting raster or vector data.

How It Works:

User: Reproject DEM to Web Mercator
AI: [Justifies CRS choice] → Cached in domain: crs_datum

User: Reproject vector layer to Web Mercator  
AI: [CACHE HIT! No re-prompting] → Reuses justification

Cache Key Formula:

hash(domain + prompt_hash + prompt_args)
# NOT: hash(tool_name + domain + ...)

Result: 75% cache hit rate in workflows (validated through user testing)

3. User Testing Validation

Round 1 Testing (Pre-Fix):

• ❌ Tool-specific caching (cache miss across raster→vector)
• Friction: 3/5
• Feedback: "Helpful with caveats"

The Fix:

• Removed tool_name from cache key hash computation
• Made reflection truly domain-based

Round 2 Testing (Post-Fix):

• ✅ Cross-domain caching working perfectly
• ✅ 75% cache hit rate (3 of 4 operations)
• Friction: 1.5/5 (50% reduction!)
• Helpfulness: 5/5 (maximum rating)
• Feedback: "Yes, confidently recommend"

Qualitative Finding:

"The very first CRS justification now unlocks subsequent vector operations (and vice versa), reducing repeated prompts and making flows feel coherent."

What This Proves

Architectural Validation:
This release validates that epistemic reasoning can be domain-based, not tool-based. Methodological knowledge about CRS choices, resampling methods, and analytical strategies applies regardless of whether you're working with raster or vector data.

Why This Matters:

• ✅ Workflows feel intelligent and context-aware
• ✅ Educational value without repetition
• ✅ Natural multi-operation composition
• ✅ Proves the reflection architecture is fundamentally sound

Breaking Changes

None. Fully backward compatible with v1.0.x.

Technical Improvements

Fixed:

• Cross-domain reflection cache sharing (commits 5e9ae5d, 810dec1)
• Server bootstrap imports for vector tool registration
• Test suite compatibility with new signatures

Quality Metrics:

• 72 automated tests passing
• Full type safety (mypy strict)
• Pre-commit hooks passing
• Zero regressions

Phase 2 Complete ✅

This release completes Phase 2 of the GDAL MCP vision:

• ✅ Epistemic middleware system (v1.0.0)
• ✅ Advisory prompting (v1.0.1)
• ✅ Vector tool parity (v1.1.1)
• ✅ Cross-domain reflection (v1.1.1)
• ✅ Comprehensive tool coverage
• ✅ Production-ready infrastructure

Next Phase: Phase 3 - Workflow Intelligence (v2.0+)

---

Installation

pip install gdal-mcp==1.1.1

Documentation

• README - Getting started
• CHANGELOG - Detailed changes
• VISION - Long-term roadmap
• ADRs - Architecture decisions

---

"Methodological reasoning that transcends data types."

This is what epistemic AI looks like in practice.

v1.0.0 - Geospatial reasoning through epistemic prompting.

[1.0.0] - 2025-10-24

🎉 Major Release - First MCP Server with Epistemic Governance

The first geospatial AI substrate with epistemic reasoning. This release introduces a reflection middleware
system that requires AI agents to justify methodological decisions before executing geospatial operations with
significant consequences.

Added

🧠 Reflection Middleware System

• FastMCP middleware interception - Pre-execution reasoning for all flagged tools
• ReflectionMiddleware - Intercepts tool calls, checks cache, triggers prompts when needed
• Declarative reflection config - Maps tools to required justifications (ReflectionSpec)
• Persistent justification cache - .preflight/justifications/{domain}/sha256:{hash}.json
• SHA256-based cache keys - Content-addressed storage for integrity and deduplication
• Automatic cache hits - Same parameters = instant execution (no re-prompting)
• Partial cache support - Independent caching per reflection domain

📝 Reflection Domains

• crs_datum - Coordinate system selection and datum transformations
  • Prompt: justify_crs_selection - Why this projection? What properties to preserve?
  • Cache key: dst_crs only (source-agnostic reasoning)
• resampling - Interpolation method choice for raster operations
  • Prompt: justify_resampling_method - How to interpolate? What artifacts acceptable?
  • Cache key: method only
• Tool integration: raster_reproject requires both CRS and resampling justifications

🔧 Structured Justification Schema

• Intent - What property/goal must be preserved
• Alternatives - Other methods considered and why rejected
• Choice - Selected method with rationale and tradeoffs
• Confidence - Low/medium/high certainty in methodology

🛠️ New Tools & Infrastructure

• store_justification - Explicit tool for AI to cache methodological reasoning
• Justification models - Pydantic schemas with full validation (Justification, Choice, Alternative)
• Cache inspection - On-disk JSON files for auditing and provenance
• Legacy API fallback - Safe handling of both FastMCP 2.0 and legacy APIs

Changed

API & Type System

• Flattened parameters - raster_reproject(uri, output, dst_crs, resampling, ...) (was nested Params object)
• tuple → list - JSON-RPC compatibility for bounds and resolution parameters
• Simplified prompts - justify_crs_selection(dst_crs) and justify_resampling_method(method) (removed unused params)
• Case-insensitive compression - deflate/DEFLATE both accepted in raster_convert

Middleware Architecture

• Middleware migration - Uses context.message.name/arguments (not deprecated context.request)
• Graceful degradation - Skips preflight if tool name undetermined (prevents hard failures)
• Improved error messages - Clear instructions: "Call prompt X with args Y, then retry"

Documentation

• README overhaul - Attention-grabbing examples, before/after comparison, real-world scenarios
• NEW: docs/REFLECTION.md - 500+ line technical deep dive (architecture, cache, integration guide)
• NEW: docs/ROADMAP.md - Strategic vision from v1.0 → v2.0
• NEW: test/TESTING_RESULTS_v1.0.0.md - Formal validation report (7/7 tests passing)
• Enhanced: test/REFLECTION_TESTING.md - Added cache behavior and source CRS placeholder docs

Fixed

• Line length compliance - Pre-commit hook formatting (100 char limit)
• Type safety - Full mypy strict mode across reflection system
• Import ordering - Ruff auto-formatting applied

Testing

Comprehensive Validation (7/7 tests passing)

1. ✅ First use - Both CRS and resampling prompts triggered
2. ✅ Cache hit - Identical parameters, no prompts (instant execution)
3. ✅ Partial cache (new CRS) - Only CRS prompt, resampling cached
4. ✅ Partial cache (new resampling) - Only resampling prompt, CRS cached
5. ✅ Full cache miss - Both parameters different, both prompts
6. ✅ Relative paths - Path resolution works, cache behavior correct
7. ✅ Lowercase compression - Case-insensitive validation works

Test Artifacts

• 7 output files created in test/data/ (test1-7*.tif)
• 6 justification files cached in .preflight/justifications/ (3 CRS, 3 resampling)
• Cache hit rate - 57% in isolated tests, >80% in realistic workflows

UX Validation

• Helpful ✅ - Guides next step only when required
• Intentional ✅ - Enforces epistemic guardrails at correct points
• Educational ✅ - Captures rationale and tradeoffs
• Verifiable ✅ - Auditable on-disk justifications with stable keys
• Non-conflicting ✅ - Minimal interruption, clear instructions, fast on cache hits

Performance

• First invocation (cache miss): ~10-30 seconds (includes LLM reasoning)
• Subsequent invocations (cache hit): ~6ms (negligible overhead)
• Cache size: ~1-2KB per justification JSON file

Technical Details

• Python 3.11+ required
• FastMCP 2.0 native middleware support
• Pydantic 2.0+ for type-safe models
• 72 comprehensive tests passing
• Full mypy strict mode compliance
• Ruff linting with pre-commit hooks

Documentation

• README.md - User-facing overview with compelling examples
• docs/ROADMAP.md - Strategic planning (v1.0 → v2.0)
• docs/REFLECTION.md - Technical deep dive for developers
• test/TESTING_RESULTS_v1.0.0.md - Formal validation report
• test/REFLECTION_TESTING.md - Manual testing guide with 7 scenarios

Philosophy

This release establishes GDAL MCP as the first MCP server with epistemic governance. AI agents must demonstrate
methodological understanding through structured reasoning before executing operations that have geospatial consequences.
The reflection system enforces domain expertise while maintaining workflow efficiency through intelligent caching.

Vision: Enable discovery of novel geospatial analysis workflows through tool composition with domain understanding,
not just prescribed procedures.

[v0.2.1] Resource and reasoning upgrades

GDAL MCP v0.2.1 Release Notes

Release Date: October 11, 2025
Codename: "Directional Awareness"

---

Overview

Version 0.2.1 is a hotfix that sharpens the Phase 2B experience delivered in v0.2.0. It refines raster statistics helpers, introduces semantically distinct directional enums, and updates documentation to reflect the changes made since the Phase 2B work landed.

This release directly advances the vision outlined in VISION.md: creating AI systems that understand spatial problems, compose analytical workflows, and bridge the gap between domain expertise and technical implementation.

[v0.2.0] Resource taxonomy, catalog system, and workspace scoping

GDAL MCP v0.2.0 Release Notes

Release Date: October 10, 2025
Codename: "Knowledge Infrastructure"

---

Overview

Version 0.2.0 introduces a comprehensive knowledge infrastructure that enables AI agents to reason about geospatial problems with domain expertise. Building on the solid foundation of v0.1.0's tool execution capabilities, this release adds the contextual awareness and reference data that transform gdal-mcp from a GDAL interface wrapper into a geospatially-enabled AI assistant.

This release directly advances the vision outlined in VISION.md: creating AI systems that understand spatial problems, compose analytical workflows, and bridge the gap between domain expertise and technical implementation.

What's New

Version 0.2.0 adds three categories of resources that provide AI agents with the knowledge to make informed geospatial decisions:

1. Catalog Resources - Workspace Awareness

Agents can now discover and inventory datasets in your workspace without explicit file paths. The catalog system automatically scans configured workspace directories, classifies files by type (raster/vector/other), and provides structured metadata for each dataset.

2. Reference Resources - Domain Knowledge

Built-in reference data for common geospatial decisions: CRS selection by region, resampling method guidance for different data types, compression options with use-case recommendations, and a geospatial terminology glossary.

3. Metadata Resources - Dataset Intelligence

Agents can inspect dataset characteristics before processing: format detection, driver information, spatial properties, and statistical summaries. This enables context-aware processing decisions.

How This Improves the Experience

Reduced Interaction Overhead

With catalog resources, agents can discover available datasets independently, reducing the need for users to provide explicit file paths or enumerate available data. This streamlines workflows and enables more natural conversational interactions.

Context-Aware Processing

Reference resources provide agents with domain knowledge about CRS selection, resampling methods, and compression options. Agents can now make informed technical decisions based on data characteristics and intended use cases, rather than relying on generic defaults.

Enhanced Reasoning Capabilities

The combination of catalog discovery, metadata inspection, and reference data enables agents to reason about geospatial problems more effectively. For example, an agent can discover a DEM, recognize it as elevation data, select appropriate resampling for terrain analysis, and choose a suitable CRS for the region—all without explicit user guidance.

Educational Support

The geospatial glossary and reference documentation help bridge knowledge gaps. Agents can explain terminology, recommend best practices, and provide context for technical decisions, making geospatial analysis more accessible to domain experts without deep GIS backgrounds.

Practical Examples

Example 1: Workspace-Aware Processing

User: "Reproject all DEMs in my workspace to UTM"
Agent: [Scans catalog for raster datasets]
       [Identifies elevation.tif and terrain.tif as DEMs]
       [Determines appropriate UTM zones from spatial bounds]
       [Selects cubic resampling for continuous elevation data]
       "Found 2 DEMs. Reprojecting elevation.tif to EPSG:32610 and terrain.tif to EPSG:32611..."

The agent discovers datasets, infers data types, and makes appropriate technical choices without requiring explicit instructions for each step.

Example 2: Informed Technical Decisions

User: "Prepare this land cover raster for web display"
Agent: [Inspects metadata: categorical raster, 30m resolution]
       [Consults resampling reference: MODE for categorical data]
       [Consults CRS reference: EPSG:3857 for web display]
       [Consults compression reference: PNG for categorical preservation]
       "Converting to Web Mercator with MODE resampling and PNG compression to preserve land cover classes."

The agent combines metadata inspection with reference knowledge to make technically sound decisions aligned with data characteristics and use case requirements.

Example 3: Educational Context

User: "Should I use bilinear or cubic resampling?"
Agent: [Consults resampling reference]
       "It depends on your data type and operation:
        - Bilinear: Fast, good for continuous data during upsampling
        - Cubic: Higher quality, better for continuous data but slower
        - For categorical data (land cover, classifications), use MODE or NEAREST instead
        What type of data are you working with?"

The agent provides contextual guidance based on reference data, helping users make informed decisions.

---

🏗️ Technical Improvements

Resource Taxonomy

We've introduced a structured URI scheme for organizing knowledge:

• catalog:// - Workspace dataset discovery

  • catalog://workspace/all - All datasets
  • catalog://workspace/raster - Raster datasets only
  • catalog://workspace/vector - Vector datasets only

• metadata:// - Dataset inspection

  • metadata://{file}/format - Driver and format details
  • metadata://{file}/raster - Raster-specific metadata
  • metadata://{file}/vector - Vector-specific metadata

• reference:// - Domain knowledge

  • reference://crs/common/{region} - CRS recommendations by region
  • reference://resampling/available - Resampling method catalog
  • reference://compression/available - Compression options
  • reference://glossary/geospatial - Terminology reference

Enhanced Security

• Path Validation Middleware: All file operations are validated against configured workspace directories
• Workspace Scoping: Prevents access to files outside allowed directories
• Detailed Error Messages: Clear guidance when paths are rejected

Code Quality

• 150+ Lint Fixes: Improved code consistency and maintainability
• Module Docstrings: Every module now has clear documentation
• Type Annotations: Better IDE support and type safety
• Test Coverage: New tests for catalog, metadata, and reference systems

---

📦 What's Included

New Resources (12 total)

Catalog Resources (3)

• Workspace dataset discovery with filtering
• Hidden file handling
• Extension-based classification

Metadata Resources (4)

• Format detection (raster/vector/unknown)
• Raster metadata extraction
• Vector metadata extraction
• Statistics computation

Reference Resources (5)

• Common CRS by region (50+ entries)
• Resampling methods with guidance (15 methods)
• Compression options (7 methods)
• Geospatial glossary (20+ terms)
• Resampling selection heuristics

New Shared Modules

• src/shared/catalog/ - Dataset scanning and caching
• src/shared/metadata/ - Format detection logic
• src/shared/reference/ - CRS, resampling, compression, glossary data
• src/shared/raster/ - Raster info and statistics
• src/shared/vector/ - Vector info extraction

Documentation

• 3 New ADRs: Resource taxonomy, context usage, catalog design
• 16 Style Guides: Python best practices and conventions
• FastMCP Context Guide: Logging and progress reporting patterns
• Project Brief: Vision and architecture overview

---

🔄 Migration Guide

Breaking Changes

None. Version 0.2.0 is fully backward compatible with v0.1.0 tool APIs.

New Capabilities

All existing tools (raster_info, raster_convert, raster_reproject, raster_stats, vector_info) continue to work exactly as before. The new resources are additive - they enhance agent capabilities without changing existing behavior.

Configuration

Dynamic Versioning: We've switched to hatch-vcs for automatic version management from git tags. No configuration changes required.

Workspace Scoping: Ensure GDAL_MCP_WORKSPACES environment variable is set to allow access to your data directories:

export GDAL_MCP_WORKSPACES="/path/to/workspace1:/path/to/workspace2"

---

🎓 Learning Resources

For Users

• QUICKSTART.md: Updated with resource examples
• README.md: New resource taxonomy section
• VISION.md: Understand the long-term direction

For Developers

• ADR-0023: Resource taxonomy and hierarchy
• ADR-0024: Context usage and logging policy
• ADR-0025: Catalog resource implementation
• docs/styleguide/: 16 guides on code quality

---

Alignment with Vision

This release directly advances the goals outlined in VISION.md:

From Command Executor to Reasoning Agent

Version 0.1.0 established reliable tool execution. Version 0.2.0 adds the knowledge infrastructure that enables agentic reasoning—agents can now understand context, consult domain knowledge, and make informed decisions rather than simply executing commands.

Building Toward Autonomous Workflows

The catalog, metadata, and reference systems provide the foundation for multi-step workflow composition. Agents can now:

• Discover what data exists
• Understand data characteristics
• Select appropriate processing methods
• Explain technical decisions

These capabilities are prerequisites for the autonomous workflow planning targeted in Phase 3.

Bridging Domain Expertise and Technical Implementation

The reference resources and glossary help bridge the gap between geospatial domain knowledge and technical GIS implementation. Domain experts can work with agents that understand both the spatial problem and the technical solution space.

What's Next

Version 0.2.0 completes Phase 2A (Resources) and sets the stage f...

v0.1.0 - First Production Release 🎉

v0.1.0 - First Production Release 🎉

Historic Milestone: First successful live GDAL MCP tool invocation through conversational AI! (2025-09-30)

🌟 Highlights

• 🚀 Production-ready CI/CD: Modular GitHub Actions pipeline with quality gates, test matrix, and automated builds
• ✨ Simplified CLI: Renamed from gdal-mcp to gdal for cleaner command-line experience
• 🔒 Security hardening: Workspace scoping, clean git history (no secrets)
• 📚 Comprehensive documentation: README, QUICKSTART, CONTRIBUTING, ADRs
• ✅ Quality assurance: All gates passing (lint, format, type check, 23/23 tests)

🎯 What's Included

Tools (5)

• raster_info - Inspect raster metadata
• raster_convert - Convert formats with compression & overviews
• raster_reproject - Reproject with explicit resampling
• raster_stats - Compute comprehensive statistics
• vector_info - Inspect vector dataset metadata

Features

• Python-native stack (Rasterio, PyProj, Shapely, Pyogrio)
• FastMCP 2.0 framework
• Workspace scoping for secure file access
• Real-time context support for LLM feedback
• Modular CI/CD with GitHub Actions
• 23/23 tests passing across Python 3.10-3.12

📦 Installation

Local development:

git clone [https://github.com/JordanGunn/gdal-mcp.git](https://github.com/JordanGunn/gdal-mcp.git)
cd gdal-mcp
uv sync
uv run gdal --help