# Botforge

> A modular AI-powered service for querying semantically indexed documents using OpenAI's GPT models and Upstash Vector database. Built with FastAPI, SentenceTransformers, and asyncio.

- **Type:** MCP server
- **Install:** `agentstack add mcp-maybeswapnil-botforge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [maybeswapnil](https://agentstack.voostack.com/s/maybeswapnil)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [maybeswapnil](https://github.com/maybeswapnil)
- **Source:** https://github.com/maybeswapnil/botforge

## Install

```sh
agentstack add mcp-maybeswapnil-botforge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🤖 BotForge RAG - Professional AI Integration Platform

[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://www.postgresql.org/)
[](https://redis.io/)
[](LICENSE)

> **Enterprise-grade AI system for intelligent document querying and dynamic tool execution with Model Context Protocol (MCP) integration**

BotForge RAG is a production-ready AI platform that seamlessly combines Retrieval-Augmented Generation (RAG) with external tool execution capabilities. The system features intelligent intent detection to automatically route queries between information retrieval and action execution pipelines, making it ideal for complex business integrations and AI-powered applications.

## 🏗️ Architecture Overview

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Query    │───▶│  Intent         │───▶│  Response       │
│                 │    │  Detection      │    │  Generation     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │  Route Query    │
                    └─────────────────┘
                              │
                 ┌────────────┼────────────┐
                 ▼                         ▼
       ┌─────────────────┐        ┌─────────────────┐
       │   RAG Pipeline  │        │  MCP Pipeline   │
       │                 │        │                 │
       │ • Vector Query  │        │ • LangChain     │
       │ • Context       │        │   Agent         │
       │   Assembly      │        │ • External      │
       │ • LLM Response  │        │   Tool Exec     │
       └─────────────────┘        └─────────────────┘
                 │                         │
                 ▼                         ▼
       ┌────────────────--─┐        ┌─────────────────┐
       │   Vector Search   │        │  External Tools │
       │   Knowledge Base. │        │  Dynamic Exec   │
       └─────────────────--┘        └─────────────────┘
```

## 🚀 Quick Start

### Prerequisites
- Python 3.11+
- [UV package manager](https://docs.astral.sh/uv/) installed

### Installation & Startup
```bash
# Clone the repository
git clone 
cd botforge-rag

# Start the application (installs dependencies automatically)
./scripts/start.sh
```

The application will be available at:
- **API**: http://localhost:8000
- **Documentation**: http://localhost:8000/docs
- **Health Check**: http://localhost:8000/health

### System Status Check
```bash
# Check if everything is working
./scripts/status.sh
```

### Development Environment
All dependencies are managed through UV and automatically installed. The system includes:
- ✅ LangChain ecosystem for AI operations
- ✅ MCP (Model Context Protocol) client for tool integration
- ✅ FastAPI for REST API
- ✅ Vector database for document storage
- ✅ Comprehensive test suite and development tools

## ✨ Enterprise Features

- 🧠 **Intelligent Intent Detection** - Advanced query classification with context awareness
- 🔄 **Unified API Architecture** - Single endpoint handles both RAG and tool execution
- 🛠️ **Dynamic MCP Integration** - Per-bot registration of external business tools
- ⚡ **High-Performance Stack** - Async processing, Redis caching, connection pooling
- 🎯 **Production-Ready RAG** - Vector similarity search with source attribution
- 🔧 **Extensible Design** - Plugin architecture for custom tools and capabilities
- 🔒 **Enterprise Security** - Bot-scoped access control and request validation
- 📊 **Comprehensive Monitoring** - Health checks, metrics, and error tracking
- 🚀 **Scalable Infrastructure** - Docker, Kubernetes, and cloud-ready deployment
- 📝 **Professional Documentation** - Complete API reference and integration guides

## 🚀 Quick Start

### Prerequisites

- **Python 3.9+** with pip or uv package manager
- **PostgreSQL 15+** for primary data storage
- **Redis 7+** for caching and session management
- **OpenAI API Key** for LLM functionality
- **Upstash Vector Database** account for embeddings

### Installation

```bash
# Clone the repository
git clone https://github.com/your-org/botforge-rag.git
cd botforge-rag

# Install dependencies using uv (recommended)
uv sync

# Alternative: Install with pip
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration (see Configuration section)

# Initialize database schema
python -c "
import asyncio
import asyncpg
from src.botforge.core.config import settings

async def init_db():
    conn = await asyncpg.connect(settings.postgres_uri)
    with open('create.sql', 'r') as f:
        await conn.execute(f.read())
    await conn.close()
    print('Database initialized successfully')

asyncio.run(init_db())
"

# Start the development server
PYTHONPATH=./src uvicorn botforge.main:app --reload --port 8000
```

### Quick Test

```bash
# Test information retrieval (RAG)
curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user",
    "bot_id": "test-bot",
    "client_id": "test-client",
    "query": "What is machine learning?",
    "model": "gpt-3.5-turbo"
  }'

# Test tool execution (MCP)
curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "test-user", 
    "bot_id": "test-bot",
    "client_id": "test-client",
    "query": "Calculate 25 * 17 + 100",
    "model": "gpt-3.5-turbo"
  }'
```

## ⚙️ Configuration

### Environment Variables

Create a `.env` file in the project root:

```bash
# Database Configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=botforge
POSTGRES_PASSWORD=your_password
POSTGRES_DB=botforge

# Redis Configuration  
REDIS_URI=redis://localhost:6379/0

# Vector Database (Upstash)
UPSTASH_URL=https://your-region-xxxxx.upstash.io
UPSTASH_TOKEN=your_upstash_token

# OpenAI Configuration
OPENAI_API_KEY=sk-your_openai_api_key
OPENAI_DEFAULT_MODEL=gpt-3.5-turbo
OPENAI_MAX_TOKENS=1000
OPENAI_TEMPERATURE=0.7

# Application Settings
UPLOAD_LOCATION=/path/to/upload/directory
DEFAULT_TOP_K=5
MAX_TOP_K=20
DEFAULT_HISTORY_SIZE=3
```

### Advanced Configuration

The system supports various configuration options through `src/botforge/core/config.py`:

- **Vector Search**: Configurable similarity thresholds and result limits
- **MCP Integration**: Timeout settings and retry policies  
- **Caching**: TTL configuration for different cache types
- **Performance**: Connection pool sizes and async operation limits

## 🔧 API Usage Examples

### Python SDK

```python
import httpx
import asyncio

class BotForgeClient:
    def __init__(self, base_url="http://localhost:8000"):
        self.base_url = base_url
        
    async def query(self, user_id, bot_id, query, client_id="python-sdk"):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/vector/query-dynamic",
                json={
                    "user_id": user_id,
                    "bot_id": bot_id,
                    "client_id": client_id,
                    "query": query,
                    "model": "gpt-3.5-turbo"
                }
            )
            return response.json()
    
    async def register_mcp_server(self, bot_id, name, endpoint_url):
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/mcp/register",
                json={
                    "bot_id": bot_id,
                    "name": name,
                    "endpoint_url": endpoint_url,
                    "description": f"External tools for {name}"
                }
            )
            return response.json()

# Usage example
async def main():
    client = BotForgeClient()
    
    # Information query (RAG)
    result = await client.query(
        user_id="user-123",
        bot_id="bot-456", 
        query="What is our company return policy?"
    )
    print(f"RAG Response: {result['response']}")
    
    # Execution query (MCP)
    result = await client.query(
        user_id="user-123",
        bot_id="bot-456",
        query="Calculate compound interest for $1000 at 5% for 10 years"
    )
    print(f"MCP Response: {result['response']}")

asyncio.run(main())
```

### JavaScript/Node.js SDK

```javascript
class BotForgeClient {
    constructor(baseUrl = 'http://localhost:8000') {
        this.baseUrl = baseUrl;
    }
    
    async query(userId, botId, query, clientId = 'javascript-sdk') {
        const response = await fetch(`${this.baseUrl}/vector/query-dynamic`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                user_id: userId,
                bot_id: botId,
                client_id: clientId,
                query: query,
                model: 'gpt-3.5-turbo'
            })
        });
        return await response.json();
    }
    
    async registerMcpServer(botId, name, endpointUrl) {
        const response = await fetch(`${this.baseUrl}/mcp/register`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                bot_id: botId,
                name: name,
                endpoint_url: endpointUrl,
                description: `External tools for ${name}`
            })
        });
        return await response.json();
    }
}

// Usage
const client = new BotForgeClient();

// Information retrieval
client.query('user-123', 'bot-456', 'What are the system requirements?')
    .then(result => console.log('Info:', result.response));

// Tool execution  
client.query('user-123', 'bot-456', 'Convert "hello world" to uppercase')
    .then(result => console.log('Tool:', result.response));
```

## 🧪 MCP Integration Example

BotForge RAG now supports **Model Context Protocol (MCP)** for professional-grade tool integration, following the same patterns as Anthropic Claude and GitHub Copilot.

### Quick Setup

```bash
# Install MCP client dependencies
./scripts/dev/install_mcp_client.sh

# Test MCP integration (requires MCP server running)
./scripts/dev/test_mcp_tools.py
```

### Implementation Options

**Option 1: Claude-Style MCP Service (Recommended)**
```python
from botforge.services.mcp_agent_service_new import MCPAgentService

async with MCPAgentService() as mcp_service:
    response = await mcp_service.query_with_mcp_agent(
        bot_id="my-bot",
        query="Use the weather tool to check temperature in Paris"
    )
    print(response)
```

**Option 2: Refactored Original Service**
```python
from botforge.services.mcp_agent_service import MCPAgentService

service = MCPAgentService()
response = await service.query_with_mcp_agent("bot-id", "your query")
```

### Key Features

- 🔧 **Proper MCP Protocol**: Uses official MCP Python client
- 🚀 **Dynamic Tool Discovery**: Automatically detects tools from MCP servers
- 🧠 **LLM-Driven Parameters**: No hardcoded tool schemas required
- ⚡ **Async Session Management**: Efficient connection handling
- 📊 **Database Integration**: Server URLs fetched dynamically from DB

### Example MCP Server Integration

```python
# Example: Weather tool with proper MCP protocol
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def use_weather_tool():
    async with streamablehttp_client(url="http://localhost:3001") as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            
            # Execute weather tool
            result = await session.call_tool("weather", {
                "location": "Paris",
                "units": "celsius"
            })
            
            return result.content[0].text
```

For detailed setup instructions, see **[docs/MCP_INTEGRATION_STATUS.md](docs/MCP_INTEGRATION_STATUS.md)**

### Step 2: Register MCP Server

```bash
curl -X POST "http://localhost:8000/mcp/register" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "your-bot-id",
    "name": "Business Tools",
    "endpoint_url": "http://localhost:3001",
    "description": "Customer management and notification tools"
  }'
```

### Step 3: Use Integrated Tools

```bash
# The bot will now automatically use external tools for relevant queries
curl -X POST "http://localhost:8000/vector/query-dynamic" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "manager-123",
    "bot_id": "your-bot-id", 
    "client_id": "business-app",
    "query": "Look up customer information for ID 12345",
    "model": "gpt-3.5-turbo"
  }'
```

## 📚 Professional Documentation

This project includes comprehensive documentation for enterprise-grade development and deployment:

### Core Documentation
- **[Architecture Guide](ARCHITECTURE.md)** - Complete system architecture, components, and data flows
- **[API Reference](docs/api.md)** - Detailed endpoint documentation with request/response examples
- **[Deployment Guide](docs/deployment.md)** - Docker, Kubernetes, and production deployment
- **[MCP Protocol Guide](docs/mcp-protocol.md)** - External MCP server integration and examples

### Implementation Guides
- **[External MCP Integration](docs/EXTERNAL_MCP_INTEGRATION.md)** - Business tool integration patterns
- **[Unified Dynamic Query System](docs/UNIFIED_DYNAMIC_QUERY_SYSTEM.md)** - Intent-based routing details
- **[MCP Agent Implementation](docs/MCP_AGENT_IMPLEMENTATION.md)** - LangChain agent development

### Key Architectural Decisions
- **Intent-based Query Routing**: Automatic classification between information retrieval and tool execution
- **Per-bot MCP Registration**: Isolated tool environments for different business contexts
- **Async-first Design**: High-performance async processing throughout the stack
- **Professional Error Handling**: Comprehensive error management with graceful degradation
- **Enterprise Security**: Bot-scoped access control and input validation

## 🏗️ System Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   User Query    │───▶│ Intent Detection│───▶│ Route Decision  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                        ┌───────────────────────────────┼───────────────────────────────┐
                        ▼                               ▼                               │
              ┌─────────────────┐                ┌─────────────────┐                    │
              │  RAG Pipeline   │                │ MCP Agent       │                    │
              │                 │                │ Pipeline        │                    │
              │ • Vector Search │                │                 │                    │
              │ • Context       │                │ • LangChain     │                    │
              │ • OpenAI LLM    │                │ • External Tools│                    │
              └─────────────────┘                └─────────────────┘                    │
                        │                               │                               │
                        ▼

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [maybeswapnil](https://github.com/maybeswapnil)
- **Source:** [maybeswapnil/botforge](https://github.com/maybeswapnil/botforge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-maybeswapnil-botforge
- Seller: https://agentstack.voostack.com/s/maybeswapnil
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.