v0.5.0 - Aquiles-RAG

Release v0.5.0 - MCP Server Integration, TypeScript/JavaScript Client, and Enhanced Documentation

In this release, native Model Context Protocol (MCP) server support has been added to Aquiles-RAG, enabling AI agents to directly interact with your vector database. A new TypeScript/JavaScript client (@aquiles-ai/aquiles-rag-client) has been published to npm, and the project structure has been enhanced with Docker examples, deployment templates, and comprehensive usage examples.

Development tracked in issue: #4
Docs for v0.5.0: https://aquiles-ai.github.io/aqRAG-docs/

Highlights

• ✅ MCP Server (First-Class Support):

  • Native Model Context Protocol server built with FastMCP
  • Expose RAG operations as MCP tools for AI agents (Claude Desktop, custom agents, etc.)
  • Four MCP tools: readiness(), create_index(), get_ind(), delete_index()
  • Custom HTTP routes: /rag/create, /create/index, /rag/query-rag
  • SSE endpoint for real-time agent communication: /sse
  • CLI command: aquiles-rag mcp to start the MCP server
  • Deploy command: aquiles-rag mcp-deploy for production deployment (Render, etc.)
  • Full authentication support via X-API-Key header

• ✅ TypeScript/JavaScript Client:

  • Published to npm as @aquiles-ai/aquiles-rag-client
  • Full TypeScript type definitions and IntelliSense support
  • Async/await API mirroring Python client functionality
  • Support for all RAG operations: create index, send chunks, query, rerank, drop index
  • Utility functions: chunkTextByWords(), extractTextFromChunk()
  • Browser and Node.js compatible
  • Complete metadata support matching v0.4.0 features

• ✅ Enhanced Project Structure:

  • docker/ folder: Complete Docker and Docker Compose examples for Redis, Qdrant, and PostgreSQL backends
  • deploy-example/ folder: Production deployment templates and configurations
  • example/ folder: Comprehensive usage examples including MCP agent workflows
  • Organized repository structure for better developer experience

• ✅ Comprehensive Documentation Updates:

  • New MCP Server documentation: Setup, tools, HTTP routes, agent examples, deployment
  • New TypeScript/JavaScript Client documentation: Installation, API reference, examples
  • Updated all code examples to reflect MCP integration patterns
  • Enhanced deployment guides with cloud platform specifics

• ✅ MCP-Ready Deployment:

  • Successfully tested on Render.com with both standard and MCP server modes
  • Environment variable configuration for production
  • Connection pooling and timeout handling for production workloads
  • Multi-backend support (Redis, Qdrant, PostgreSQL) in MCP mode

New Features

MCP Server Tools

The MCP server exposes four tools that AI agents can invoke:

1. readiness() - Check database connection status

2. create_index() - Create vector indices

3. get_ind() - List all indices

4. delete_index() - Remove indices

TypeScript/JavaScript Client API

import { AsyncAquilesRAG, ChunkMetadata } from '@aquiles-ai/aquiles-rag-client';

const client = new AsyncAquilesRAG({
  host: 'http://localhost:5500',
  apiKey: 'your-api-key',
  timeout: 30000
});

// Create index
await client.createIndex('my_index', 1536, 'FLOAT32', true);

// Send data with metadata
const metadata: ChunkMetadata = {
  author: 'John Doe',
  language: 'EN',
  topics: ['AI', 'RAG'],
  source: 'documentation'
};

await client.sendRAG(
  embeddingFunction,
  'my_index',
  'doc_1',
  'Long text...',
  { embeddingModel: 'text-embedding-3-small', metadata }
);

// Query
const results = await client.query('my_index', queryEmbedding, {
  topK: 5,
  cosineDistanceThreshold: 0.6
});

// Rerank
const reranked = await client.reranker('query text', results);

CLI Commands

Start MCP Server (Development)

# Default port 5500
aquiles-rag mcp-serve

# Custom port
aquiles-rag mcp-serve --port 8080

Deploy MCP Server (Production)

# Deploy to Render or similar platforms
aquiles-rag mcp-deploy

Project Structure Updates

New Folders

docker/ - Docker and Docker Compose configurations

docker/
├── docker-compose.yaml
├── Dockerfile.mcp
├── Dockerfile.redis
├── .env.example
├── deploy_redis.py
├── requirements.txt
└── README.md

deploy-example/ - Deployment templates

deploy-example/
├── deploy_qdrant.py
└── deploy_redis.py

example/ - Usage examples

example/
├── client_example.py
└── mcp_example.py

MCP Agent Integration Example

import asyncio
from agents import Agent, Runner, function_tool
from agents.mcp import MCPServerSse
from aquiles.client import AsyncAquilesRAG

async def main():
    # Connect to MCP server
    mcp_server = MCPServerSse({
        "url": "http://localhost:5500/sse",
        "headers": {"X-API-Key": "your-api-key"}
    })
    await mcp_server.connect()

    # Create agent with MCP tools
    agent = Agent(
        name="Aquiles Assistant",
        instructions="You have access to Aquiles-RAG MCP tools...",
        mcp_servers=[mcp_server],
        tools=[
            function_tool(send_info, name_override="send_info"),
            function_tool(query_rag, name_override="query_rag")
        ],
        model="gpt-5"
    )

    # Run agent task
    result = await Runner.run(agent, """
        1. Create an index with 1536 dimensions
        2. Store documents about AI
        3. Query for 'machine learning'
        4. Report results
    """)
    
    print(result.final_output)
    await mcp_server.cleanup()

asyncio.run(main())

Migration & Upgrade Notes

1. Install latest version:

   uv pip install --upgrade aquiles-rag==0.5.0

2. Install TypeScript/JavaScript client:

   npm i @aquiles-ai/aquiles-rag-client

3. MCP Server setup:

   • Use aquiles-rag mcp-serve to start the server
   • Configure API key via environment variable or config file
   • Deploy to production with aquiles-rag mcp-deploy

4. Documentation updates:

   • Visit Aquiles-RAG Docs for complete guides

5. Docker usage:

   • Explore docker/ folder for backend setup examples
   • Use provided docker-compose files for local development

Deployment

Local Development

# Start MCP server
aquiles-rag mcp-serve

Production (Render.com)

# Deploy command handles configuration
aquiles-rag mcp-deploy

The MCP server has been successfully tested on Render.com with both standard and MCP deployment modes.

Changelog (Summary)

• Added MCP server with FastMCP integration
• Added Four MCP tools: readiness, create_index, get_ind, delete_index
• Added Custom HTTP routes for MCP server: /rag/create, /create/index, /rag/query-rag
• Added SSE endpoint /sse for real-time agent communication
• Added CLI commands: aquiles-rag mcp and aquiles-rag mcp-deploy
• Added TypeScript/JavaScript client published to npm
• Added docker/ folder with Docker Compose examples
• Added deploy-example/ folder with deployment templates
• Added example/ folder with comprehensive usage examples
• Updated Documentation with MCP and TypeScript client guides
• Updated Project structure for better organization
• Updated README with MCP integration information
• Tested Production deployment on Render.com

Documentation

Complete documentation is available at:

• Docs: https://aquiles-ai.github.io/aqRAG-docs/

npm Package

The TypeScript/JavaScript client is now available on npm:

npm install @aquiles-ai/aquiles-rag-client

Package: @aquiles-ai/aquiles-rag-client

Repository Links

• Docker Examples: docker/

• Deployment Examples: deploy-example/

• Usage Examples: example/

Breaking Changes

None. This release is fully backwards compatible with v0.4.0.

Thanks & Credits

Special thanks to everyone who contributed to testing the MCP server integration and providing feedback on the TypeScript client. This release represents a major milestone in making Aquiles-RAG the most agent-friendly RAG runtime available.

The complete MCP server implementation and documentation is now officially available, along with the new JavaScript/TypeScript client for cross-platform compatibility.

If you encounter any issues or have feature requests, please open an issue on GitHub or reference #4 for MCP-related discussions.

Happy building with Aquiles-RAG! 🚀🤖