v0.0.4

Release v0.0.4 - Audit Trail & Tool Agent Improvements

🎉 Overview

Version 0.0.4 introduces comprehensive audit trail capabilities and significant improvements to the tool agent for generating tool specifications from Astra DB tables.

✨ New Features

Audit Trail System

• Automatic Audit Logging: Track all tool executions with detailed audit records stored in Astra DB
• Audit Table Management: Automatic creation and management of audit tables in Astra DB
• Comprehensive Audit Data: Capture tool executions with:
  • Tool ID and run ID (UUID-based)
  • Client identification
  • Start and end timestamps
  • Execution parameters and results
  • Error tracking and status information
  • Status codes and detailed messages
• Configurable Audit: Enable audit trail via --audit flag or ASTRA_DB_AUDIT_TABLE_NAME environment variable
• Partitioned Storage: Audit tables use efficient partitioning by tool ID and date for optimal query performance

Enhanced Tool Agent

• Improved Tool Specification Generation: Enhanced AI-powered tool specification generation from table schemas
• Better Prompt Engineering: New customizable prompt system for tool generation (tool_agent_prompt.py)
• Additional Instructions Support: Pass custom instructions to guide tool specification generation
• Prompt Export: Export and customize the prompts used for tool generation
• Enhanced Schema Analysis: Better understanding of partition keys, sorting keys, and indexed columns
• Smart Parameter Generation: Automatic generation of date range and numeric range parameters for indexed columns

🔧 Improvements

• Database Layer Enhancements: Improved database operations with better error handling and logging
• Tool Execution Middleware: Enhanced middleware for tracking tool execution lifecycle
• Logging System: Improved logging with better context and structured information
• Documentation Updates: Comprehensive README updates with new features and usage examples

📦 New Examples

• Airline Tool Example: New example tool specification generated by the tool agent (examples/tools/airline_tool_by_agent.json)
• Tool Agent Prompt Template: Example prompt file for tool specification generation (examples/prompts/tool_agent_prompt.md)
• Organized Examples: Better organization of example tools and configurations

🛠️ Technical Changes

• Added audit.py module for audit table definitions
• Enhanced database.py with audit trail setup and logging methods
• Improved run_tool.py middleware with audit integration
• Enhanced tool_agent.py with better prompt handling and instructions
• New tool_agent_prompt.py module for prompt management
• Updated logger configuration and utilities

📋 Configuration

To enable audit trail, set the following environment variable:

ASTRA_DB_AUDIT_TABLE_NAME=mcp_audit_trail

And use the command-line flag:

uvx astra-mcp-server --audit

🔄 Migration Notes

• When audit is enabled, the audit table is automatically created on first use
• No breaking changes to existing APIs or tool configurations

📚 Documentation

• Updated README with audit trail configuration details

🐛 Bug Fixes

• Improved error handling in tool execution
• Better validation of tool parameters
• Enhanced logging for debugging

v0.0.3

🚀 Astra MCP Server v0.0.3 - Release Summary

Version 0.0.3 represents a significant evolution of the Astra MCP Server, introducing AI-powered automation, enhanced database support, and improved developer experience while maintaining full backward compatibility with existing deployments.

🆕 Major New Features

1. AI-Powered Tool Agent
   New Command: astra-mcp-tool-agent - Automatically generates tool specifications by analyzing Astra DB tables
   Smart Analysis: Connects to Astra DB, retrieves table schema, and analyzes sample data to create optimized tool configurations
   LLM Integration: Uses OpenAI GPT-4o-mini to intelligently generate tool parameters based on actual table structure
   Flexible Configuration: Supports custom instructions and sample size adjustments

2. Enhanced Database Support

Table Support: Extended beyond collections to support Astra DB tables (CQL tables)
Unified Interface: Single find() method that works with both collections and tables
Schema Awareness: Automatically detects partition keys, sorting keys, and indexed columns
Vector Column Detection: Identifies vector columns for embedding-based searches

3. Catalog Management System

New Command: astra-mcp-catalog - Upload and manage tool catalogs in Astra DB
Batch Operations: Upload multiple tools at once with automatic cleanup of existing tools
Collection Management: Automatically creates collections if they don't exist
Flexible Storage: Store tool catalogs in custom collections with configurable names

🔧 Technical Improvements

4. Enhanced LLM Integration

Multi-Provider Support: Added support for both OpenAI and IBM Watsonx embedding models
Model Flexibility: Support for various embedding models including:
OpenAI: text-embedding-3-small, text-embedding-3-large, text-embedding-ada-002
IBM Watsonx: granite-embedding-278m-multilingual, all-minilm-l6-v2, and more
Prompt Engineering: Intelligent tool specification generation with context-aware prompts

5. Improved Configuration Management
   Environment Variable Support: Enhanced command-line argument handling with fallback to environment variables
   Flexible Authentication: Streamlined Astra DB connection with better error handling
   Dynamic Configuration: Runtime configuration updates without server restart

6. Enhanced Tool Specification Format

Rich Metadata: Added info field to parameters indicating column types (partition key, indexed, vector)
Smart Parameter Generation: Automatic generation of range parameters for dates and numbers
Embedding Integration: Automatic embedding model assignment for vector columns
Projection Optimization: Intelligent field selection excluding technical metadata

📊 Example Tool Specifications

The release includes two example tool specifications:
Product Search Tool (products_tool.json):
E-commerce product search with color, price, and availability filters
Vector search capabilities for semantic product matching
Range-based filtering for prices and release dates
Airline Tickets Tool (user_tool.json):
Customer-specific ticket retrieval
Airport-based filtering
Comprehensive flight information projection

🛠️ Developer Experience Improvements

7. Better Error Handling
   Comprehensive Logging: Enhanced logging throughout the application
   Graceful Failures: Better error messages and fallback mechanisms
   Validation: Improved input validation for tool specifications

8. Documentation Updates

Comprehensive README: Updated with new features and usage examples
Build Instructions: Enhanced BUILD.md with complete release workflow
Integration Guides: Added examples for Langflow and IBM Orchestrate

🔄 Backward Compatibility
Seamless Migration: All existing tool configurations continue to work
Gradual Adoption: New features are optional and don't break existing setups
Environment Flexibility: Maintains support for both file-based and database-based tool catalogs

📈 Performance Enhancements
Optimized Queries: Better handling of indexed columns and partition keys
Reduced Latency: Streamlined database operations
Memory Efficiency: Improved resource management for large datasets

0.0.2

Adding:

• More filter and operator options
• Integration with OpenAI and IBM Watson for embedding models

v0.0.1 Hello World

Astra MCP Server v0.0.1 Release Description

🎉 Initial Release - Astra MCP Server

This is the first release of the Astra MCP Server, a Model Context Protocol (MCP) server that enables seamless integration between AI applications and DataStax Astra DB.

✨ Key Features

🔗 Astra DB Integration

• Integration with DataStax Astra DB using the official astrapy client
• Support for both HTTP and STDIO transport protocols
• Configurable database connection via environment variables

🛠️ Dynamic Tool System

• Configurable tool catalog system supporting both file-based and Astra collection-based configurations
• Built-in database tools: find_documents and list_collections
• Support for vector search operations with $vectorize queries

🚀 Flexible Deployment

• Command-line interface with comprehensive argument parsing
• Support for both development (--reload) and production modes
• Configurable host, port, and logging settings
• Easy installation via uv package manager

📊 Advanced Features

• Comprehensive logging system with configurable levels and file output
• Middleware support for custom tool execution workflows
• Utility functions for data transformation and key renaming
• Support for projection, filtering, and pagination in database queries

🔧 Developer Experience

• Support for MCP Inspector for debugging and testing
• Environment-based configuration management

📦 Installation & Usage

# Quick start from GitHub
uvx git+https://github.com/smatiolids/astra-mcp-server.git

# Local development
uv sync
uv run astra-mcp-server --host 127.0.0.1 --port 5150 --reload --log-level debug

🎯 Use Cases

• RAG Applications: Vector search and retrieval from Astra collections
• Product Search: Configurable product search with filtering capabilities
• FAQ Systems: Question-answering systems using vectorized content
• Custom Database Operations: Flexible tool configuration for specific use cases

🔧 Configuration

The server supports configuration via:

• Environment variables (.env file)
• Command-line arguments
• JSON configuration files
• Astra DB collections for tool catalogs

📋 Requirements

• Python 3.12+
• DataStax Astra DB account
• Required dependencies: astrapy, fastmcp, uvicorn, python-dotenv

This initial release provides a solid foundation for building AI applications that interact with Astra DB through the Model Context Protocol, with extensive customization options and developer-friendly tooling.