# Using PostgreSQL Analyzer with Nanobot

## Compatibility

| Component | Works with Nanobot? | Notes |
|-----------|---------------------|-------|
| **MCP Server** (`pg_mcp_server/server.py`) | ✅ **YES** | Nanobot fully supports MCP servers (added in v0.1.4) |
| **Skill** (`pg_analyzer_skill/SKILL.md`) | ❌ **NO** | Nanobot has its own skill system (different from Kimi CLI) |

## What is Nanobot?

[Nanobot](https://nanobot.ai/) is an ultra-lightweight (~4,000 lines of Python) AI agent framework and OpenClaw alternative. It's built entirely on the **Model Context Protocol (MCP)**.

**Key differences from Kimi Code CLI:**
- Kimi CLI: Uses skills (SKILL.md) + MCP
- Nanobot: Uses MCP natively + its own Python-based skill system

## Installation

```bash
# Via Homebrew (macOS/Linux)
brew install nanobot-ai/tap/nanobot

# Or via pip
pip install nanobot-ai

# Or via uv
uv tool install nanobot-ai
```

## Configuration

### 1. Create `nanobot.yaml` Config File

```yaml
# nanobot.yaml
agents:
  postgres-analyst:
    name: PostgreSQL Data Analyst
    description: Analyzes PostgreSQL databases and answers data questions
    model: openrouter/gpt-4o  # or any model you prefer
    
    # MCP servers this agent can use
    mcpServers:
      - postgres
    
    # System prompt (replaces SKILL.md functionality)
    systemPrompt: |
      You are a PostgreSQL data analyst. You help users explore their database
      and extract insights using SQL queries.
      
      When the user asks about data:
      1. Use the postgres MCP tools to query the database
      2. Available tools: get_schema, execute_query, get_table_stats, analyze_column
      3. Always start with get_schema if user asks about "database" or "tables"
      4. For specific questions, use execute_query with appropriate SQL
      5. Present results clearly with insights
      
      Safety: Only SELECT queries are allowed. The MCP server enforces read-only.

# MCP server definitions
mcpServers:
  postgres:
    # stdio transport (local process)
    transport: stdio
    command: python3
    args:
      - /absolute/path/to/pg_mcp_server/server.py
    env:
      PG_CONNECTION_STRING: "postgresql://user:pass@localhost:5432/db"
    
    # Alternative: If you wrap it as an HTTP server
    # transport: http
    # url: http://localhost:3000/mcp
```

### 2. Project Structure for Nanobot

```
pg_analyzer_demo/
├── pg_mcp_server/           # MCP Server (✅ USE WITH NANOBOT)
│   ├── server.py
│   └── requirements.txt
├── pg_analyzer_skill/       # Skill (❌ NOT COMPATIBLE - Kimi CLI only)
│   └── SKILL.md
├── nanobot.yaml             # ✅ NEW: Nanobot configuration
└── nanobot_skill.py         # ✅ NEW: Nanobot Python skill (optional)
```

### 3. Run Nanobot

```bash
# Start the agent
nanobot run ./nanobot.yaml

# Or use the agent CLI
nanobot agent postgres-analyst
```

## Alternative: Python Skill for Nanobot

Instead of relying on the system prompt, you can create a proper Nanobot skill:

```python
# postgres_skill.py
from nanobot import skill, Context

@skill(name="postgres-analyzer")
class PostgresAnalyzerSkill:
    """PostgreSQL database analysis skill for Nanobot."""
    
    @skill.intent("analyze database")
    async def analyze_database(self, ctx: Context):
        """When user wants to analyze their database."""
        # This skill can call MCP tools via ctx.mcp
        schema = await ctx.mcp.postgres.get_schema()
        return f"Database has these tables:\n{schema}"
    
    @skill.intent("expensive book")
    async def expensive_book(self, ctx: Context):
        """When user asks about expensive books."""
        result = await ctx.mcp.postgres.execute_query(
            query="""
                SELECT name, price 
                FROM products 
                WHERE category = 'Books' 
                ORDER BY price DESC 
                LIMIT 1
            """
        )
        return f"The most expensive book is: {result}"
```

Then register in `nanobot.yaml`:

```yaml
agents:
  postgres-analyst:
    # ... other config ...
    skills:
      - postgres_skill.py
```

## Complete Working Example

### nanobot.yaml

```yaml
agents:
  data-analyst:
    name: Data Analyst
    model: anthropic/claude-3-5-sonnet
    mcpServers:
      - postgres
    systemPrompt: |
      You are a helpful data analyst with access to a PostgreSQL database.
      
      GUIDELINES:
      - Use get_schema() to explore database structure
      - Use execute_query() for custom SQL
      - Use get_table_stats() for table overviews
      - Use analyze_column() for column details
      
      ANALYSIS WORKFLOW:
      1. Discovery: get_schema() to see tables
      2. Deep dive: get_table_stats() for specific tables
      3. Investigation: analyze_column() or execute_query()
      4. Insights: Synthesize findings with context
      
      Always explain your reasoning and show the SQL used.

mcpServers:
  postgres:
    transport: stdio
    command: python3
    args:
      - /Users/tigeren/Dev/agent_demo/pg_analyzer_demo/pg_mcp_server/server.py
    env:
      PG_CONNECTION_STRING: "postgresql://postgres:demo@localhost:5432/shop"
```

### Usage

```bash
# Start nanobot with this config
nanobot run ./nanobot.yaml

# Then in the chat:
User: What's the most expensive book?

Nanobot: [Uses MCP tool execute_query]
Result: The most expensive book is "Novel Collection" at $65.00.
It has sold 212 copies, generating $28,626 in revenue.
```

## Comparison: Kimi CLI vs Nanobot

| Feature | Kimi Code CLI | Nanobot |
|---------|--------------|---------|
| **MCP Support** | ✅ Yes | ✅ Yes (native) |
| **Skill System** | SKILL.md (markdown) | Python decorators |
| **Codebase** | ~中型 | ~4,000 lines |
| **Memory** | ~200MB | ~45MB |
| **Startup** | ~2-3s | ~0.8s |
| **Transport** | stdio, http | stdio, http, sse |
| **Platform** | CLI | CLI + Web UI |

## Migration Guide: Kimi Skill → Nanobot

### Kimi Skill (SKILL.md)
```markdown
---
name: postgres-analyzer
description: PostgreSQL analysis...
---

## Available Tools
| Tool | Purpose |
|------|---------|
| execute_query | Run SQL |

## Workflow
1. get_schema()
2. execute_query()
```

### Nanobot Equivalent
```python
# postgres_skill.py
from nanobot import skill, Context

@skill(name="postgres-analyzer", 
       description="PostgreSQL analysis and querying")
class PostgresSkill:
    
    @skill.tool_usage("execute_query")
    async def query_data(self, ctx: Context, query: str):
        """Run SQL queries."""
        return await ctx.mcp.postgres.execute_query(query=query)
    
    @skill.workflow("analyze_database")
    async def analyze(self, ctx: Context):
        """Analysis workflow."""
        # Step 1: Schema
        schema = await ctx.mcp.postgres.get_schema()
        # Step 2: Stats
        # ... etc
```

## Troubleshooting

### MCP Server Not Found
```bash
# Use absolute path in nanobot.yaml
args:
  - /absolute/path/to/pg_mcp_server/server.py
```

### Environment Variables Not Passed
```yaml
mcpServers:
  postgres:
    transport: stdio
    command: python3
    args: [server.py]
    env:
      PG_CONNECTION_STRING: "..."  # Must be explicit
```

### Connection Issues
```bash
# Test MCP server manually first
export PG_CONNECTION_STRING="..."
python3 pg_mcp_server/server.py

# In another terminal, test with mcp CLI
mcp test postgres
```

## References

- [Nanobot Documentation](https://nanobot.ai/docs)
- [Nanobot GitHub](https://github.com/hkuds/nanobot)
- [MCP Specification](https://modelcontextprotocol.io/)