Metadata-Version: 2.4
Name: stache-tools
Version: 0.1.1
Summary: Utilities and tools for the Stache RAG system
Project-URL: Homepage, https://github.com/stache-ai/stache-tools
Project-URL: Repository, https://github.com/stache-ai/stache-tools
Project-URL: Issues, https://github.com/stache-ai/stache-tools/issues
Author: Stache Team
License: MIT
License-File: LICENSE
Keywords: cli,mcp,rag,stache
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: httpx-auth>=0.22.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pypdf>=4.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0
Requires-Dist: stache-ai-documents>=0.1.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: all
Requires-Dist: boto3>=1.26.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: boto3>=1.26.0; extra == 'dev'
Requires-Dist: moto>=5.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: lambda
Requires-Dist: boto3>=1.26.0; extra == 'lambda'
Description-Content-Type: text/markdown

# stache-tools

CLI and MCP server for the [Stache](https://github.com/stache-ai/stache-ai) knowledge base.

## Installation

```bash
pip install stache-tools
```

This provides two commands:
- `stache` - CLI for interacting with your knowledge base
- `stache-mcp` - MCP server for Claude Desktop/Claude Code integration

## Quick Start

### 1. Start Stache Server

See the [Stache repository](https://github.com/stache-ai/stache-ai) for full setup instructions, or quick start:

```bash
git clone https://github.com/stache-ai/stache-ai.git
cd stache
docker compose -f docker-compose.yml -f docker-compose.local.yml up -d
```

### 2. Configure MCP Server

Add to your Claude config file:

**Claude Code** (`~/.claude.json` or `%APPDATA%\.claude\config.json` on Windows):
```json
{
  "mcpServers": {
    "stache-local": {
      "command": "stache-mcp",
      "env": {
        "STACHE_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

**Claude Desktop** (`~/.config/claude/claude_desktop_config.json` or `%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "stache-local": {
      "command": "python",
      "args": ["-m", "stache_tools.mcp"],
      "env": {
        "STACHE_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

### 3. Restart Claude

Restart Claude Code/Desktop to load the MCP server.

## MCP Tools

| Tool | Description |
|------|-------------|
| `search` | Semantic search in your knowledge base |
| `ingest_text` | Add text content |
| `list_namespaces` | List all namespaces |
| `list_documents` | List documents |
| `get_document` | Get document by ID |
| `delete_document` | Delete document |
| `create_namespace` | Create namespace |
| `get_namespace` | Get namespace details |
| `update_namespace` | Update namespace |
| `delete_namespace` | Delete namespace |

## CLI Usage

```bash
# Set API URL
export STACHE_API_URL=http://localhost:8000

# Health check
stache health

# Search
stache search "your query" -n namespace -k 10

# Ingest
stache ingest ./document.pdf -n research
stache ingest ./docs/ -n documentation -r  # Recursive
stache ingest -t "Some text content" -n notes

# Namespaces
stache namespace list
stache namespace create mba/finance --name "Finance Notes"

# Documents
stache doc list -n research
stache doc get DOC_ID
stache doc delete DOC_ID
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `STACHE_API_URL` | API base URL | `http://localhost:8000` |
| `STACHE_TRANSPORT` | Transport: `auto`, `http`, `lambda` | `auto` |
| `STACHE_TIMEOUT` | Request timeout (seconds) | `60` |

### AWS Lambda Transport

For direct Lambda invocation (bypasses API Gateway):

```bash
pip install stache-tools[lambda]
```

```json
{
  "mcpServers": {
    "stache": {
      "command": "stache-mcp",
      "env": {
        "STACHE_LAMBDA_FUNCTION": "stache-api",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

## Python API

```python
from stache_tools import StacheAPI

with StacheAPI() as api:
    # Ingest
    api.ingest_text("Your content here", namespace="examples")

    # Search
    results = api.search("query", namespace="examples")
    for source in results.get("sources", []):
        print(f"{source['score']:.3f}: {source['content'][:100]}")
```

## Documentation

- [Full Setup Guide](https://github.com/stache-ai/stache-tools/blob/main/docs/SETUP.md) - Detailed installation and configuration
- [Troubleshooting](https://github.com/stache-ai/stache-tools/blob/main/docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Stache Server](https://github.com/stache-ai/stache-ai) - Main Stache repository

## License

MIT
