Which integrations are available for this server?

Includes specialized scripts for scraping and interacting with Google Maps data. Utilizes Supabase as a registry backend for storing, versioning, and publishing AI directives, Python scripts, and knowledge entries. Provides shared utility libraries for processing YouTube data, such as extracting video identifiers within executed scripts.

How do I use Kiwi MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Kiwi MCP search the registry for a script to scrape Google Maps" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Kiwi MCP - Unified AI Agent Tools

A unified MCP (Model Context Protocol) server consolidating directives, scripts, and knowledge management into 4 simple tools.

Status: ✅ Ready for Production
Version: 0.1.0
Coverage: >85%

Overview

Kiwi MCP reduces 17 tools from three separate MCPs into 4 unified tools with consistent interfaces:

Tool	Purpose
search	Find directives, scripts, or knowledge entries (local or registry)
load	Download items from registry to local storage
execute	Run operations: publish, delete, create, update, link, run
help	Get usage guidance and troubleshooting

Supported Types:

directive - Workflow guides and configurations
script - Python execution scripts
knowledge - Zettelkasten knowledge entries

Installation

Prerequisites

Python ≥3.11
pip or poetry

From Source

cd kiwi-mcp
pip install -e ".[dev]"

Dependencies

mcp>=1.0.0 - Model Context Protocol
pydantic>=2.0.0 - Data validation
httpx>=0.27.0 - HTTP client
supabase>=2.0.0 - Registry backend
python-dotenv>=1.0.0 - Environment configuration
pyyaml>=6.0.0 - YAML parsing
aiofiles>=23.0.0 - Async file I/O

Quick Start

Initialize

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SECRET_KEY="your-secret-key"

# Run server
python -m kiwi_mcp.server

Usage Examples

Search for Directives

{
  "tool": "search",
  "arguments": {
    "item_type": "directive",
    "query": "authentication setup",
    "source": "registry",
    "limit": 10
  }
}

Response:

{
  "results": [
    {
      "name": "oauth_setup",
      "category": "authentication",
      "description": "Setup OAuth with Google and GitHub",
      "quality_score": 95.0
    }
  ]
}

Load a Script

{
  "tool": "load",
  "arguments": {
    "item_type": "script",
    "item_id": "google_maps_scraper",
    "destination": "project",
    "project_path": "/home/user/myproject"
  }
}

Response:

{
  "status": "loaded",
  "name": "google_maps_scraper",
  "version": "2.1.0",
  "destination": "project",
  "path": "/home/user/myproject/.ai/scripts/scraping/google_maps_scraper.py"
}

Run a Directive

{
  "tool": "execute",
  "arguments": {
    "item_type": "directive",
    "action": "run",
    "item_id": "bootstrap_project",
    "parameters": {
      "project_name": "my_app",
      "language": "python"
    }
  }
}

Response:

{
  "action": "run",
  "name": "bootstrap_project",
  "source": "local",
  "content": "# Bootstrap Directive\n1. Create project structure...",
  "instructions": "Follow the directive steps above."
}

Publish to Registry

{
  "tool": "execute",
  "arguments": {
    "item_type": "knowledge",
    "action": "publish",
    "item_id": "001-email-deliverability",
    "parameters": {
      "version": "1.0.0",
      "changelog": "Initial release with best practices"
    }
  }
}

Tools Reference

search

Find items by natural language query across local and registry sources.

Parameters:

item_type (required): "directive", "script", or "knowledge"
query (required): Natural language search query
source (optional): "local", "registry", or "all" (default: "local")
limit (optional): Max results (default: 10)

Returns: JSON with results array or error

Examples:

# Search for email-related knowledge
search(
    item_type="knowledge",
    query="email deliverability",
    source="registry"
)

# Search local scripts
search(
    item_type="script",
    query="scrape Google Maps",
    limit=5
)

load

Download items from registry to local storage.

Parameters:

item_type (required): "directive", "script", or "knowledge"
item_id (required): Item identifier
destination (optional): "project" or "user" (default: "project")
project_path (optional): Required if destination="project"
version (optional): Specific version to load

Returns: JSON with status, path, and metadata

Examples:

# Load directive to project
load(
    item_type="directive",
    item_id="oauth_setup",
    destination="project",
    project_path="/home/user/myapp"
)

# Load knowledge to user space
load(
    item_type="knowledge",
    item_id="001-jwt-auth",
    destination="user"
)

execute

Run operations on items: run, publish, delete, create, update, link.

Parameters:

item_type (required): "directive", "script", or "knowledge"
action (required): "run", "publish", "delete", "create", "update", "link"
item_id (required): Item identifier
parameters (optional): Action-specific parameters dict
Additional parameters: dry_run, project_path, etc.

Returns: JSON with operation result or error

Supported Actions (All Types):

All item types support the same 6 actions for consistency:

run - Execute/load the item (directives return parsed content, scripts execute with params, knowledge returns entry)
publish - Publish to registry with version
delete - Remove from local or registry (requires confirm: true)
create - Create new item locally
update - Modify existing item
link - Link to another item of the same type (e.g., directive → directive, script → script)

Type-Specific Behavior:

Action	Directive	Script	Knowledge
`run`	Returns parsed XML content	Executes in venv with params	Returns entry content
`publish`	Creates version with content_hash	Uploads .py file with metadata	Publishes with tags
`link`	`requires`, `suggests`, `extends`	`depends_on`, `imports`	`references`, `contradicts`, `extends`

Examples:

# Run a directive
execute(
    item_type="directive",
    action="run",
    item_id="setup_auth",
    parameters={"provider": "google"}
)

# Publish script to registry
execute(
    item_type="script",
    action="publish",
    item_id="my_scraper",
    parameters={"version": "1.0.0"}
)

# Delete with confirmation
execute(
    item_type="knowledge",
    action="delete",
    item_id="001-old-entry",
    parameters={"confirm": True}
)

help

Get usage guidance, examples, and troubleshooting.

Parameters:

topic (optional): Specific topic for help

Returns: JSON with help text

Examples:

# General help
help()

# Help for search tool
help(topic="search")

# Help for directive workflows
help(topic="directive")

Configuration

Environment Variables

# Supabase registry (optional)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SECRET_KEY=your-secret-key

# User space directory (optional, defaults to ~/.ai)
USER_SPACE=~/.ai

# Log level
LOG_LEVEL=INFO

.env Files

Environment variables can be loaded from hierarchical .env files:

# Userspace defaults (applies to all projects)
~/.ai/.env

# Project-specific overrides
.ai/.env

Scripts automatically load both files in order (userspace → project → runtime).

Script Execution Features

Virtual Environment Isolation

Scripts run in isolated virtual environments:

Project scripts: .ai/scripts/.venv/
Userspace scripts: ~/.ai/.venv/

Each environment is automatically created and managed.

Dependency Auto-Install

Dependencies are automatically detected and installed:

From script import statements
From lib module imports
Supports version constraints

# Script automatically installs: requests, beautifulsoup4
import requests
from bs4 import BeautifulSoup
from lib.http_session import get_session  # Also installs lib dependencies

Shared Libraries

Scripts can import from shared library modules:

# Project lib (priority)
from lib.project_utils import helper

# Userspace lib (fallback)
from lib.http_session import get_session
from lib.youtube_utils import extract_video_id

Library locations:

.ai/scripts/lib/ (project)
~/.ai/scripts/lib/ (userspace)

Output Management

Large script outputs are automatically saved:

Project: .ai/outputs/scripts/{script_name}/
Userspace: ~/.ai/outputs/scripts/{script_name}/
Keeps last 10 outputs per script
Auto-truncates MCP responses >1MB

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     MCP Server                              │
├──────────────┬──────────────┬──────────────┬────────────────┤
│   search     │     load     │   execute    │      help      │
└──────┬───────┴──────┬───────┴──────┬───────┴────────┬───────┘
       │              │              │                │
       └──────────────┴──────────────┴────────────────┘
              TypeHandlerRegistry
       ┌──────────┬──────────┬──────────┐
       │          │          │          │
   Directive   Script    Knowledge    (Future)
   Handler     Handler    Handler
       │          │          │
       ├──────────┼──────────┤
       │  Local + Registry Storage

Project Structure

kiwi-mcp/
├── kiwi_mcp/
│   ├── __init__.py              # Package
│   ├── server.py                # MCP server entry
│   ├── tools/                   # 4 unified tools
│   │   ├── base.py              # BaseTool abstract class
│   │   ├── search.py            # SearchTool
│   │   ├── load.py              # LoadTool
│   │   ├── execute.py           # ExecuteTool
│   │   └── help.py              # HelpTool
│   ├── handlers/                # Type-specific handlers
│   │   ├── registry.py          # TypeHandlerRegistry
│   │   ├── directive/           # Directive handlers
│   │   ├── script/              # Script handlers
│   │   └── knowledge/           # Knowledge handlers
│   ├── api/                     # Registry clients
│   │   ├── directive_registry.py
│   │   ├── script_registry.py
│   │   └── knowledge_registry.py
│   └── utils/                   # Shared utilities
├── tests/
│   ├── unit/
│   │   ├── test_tools.py        # Tool tests (20+)
│   │   └── test_handlers.py     # Handler tests (20+)
│   └── integration/
├── docs/                        # Documentation
├── README.md                    # This file
├── pytest.ini
└── pyproject.toml

Testing

Run All Tests

pytest tests/ -v

Run Unit Tests Only

pytest tests/unit/ -v

Coverage Report

pytest tests/ -v --cov=kiwi_mcp --cov-report=html
# Open htmlcov/index.html

Coverage Target

Goal: >85% code coverage
Current: ✅ Achieved

Development

Install Dev Dependencies

pip install -e ".[dev]"

Code Quality

# Linting
ruff check kiwi_mcp/

# Format
ruff format kiwi_mcp/

# Type checking
mypy kiwi_mcp/ --ignore-missing-imports

Running Locally

# Development server
python -m kiwi_mcp.server

# Or with auto-reload
pytest-watch tests/

API Reference

Item Types

directive

Location: .ai/directives/ (project) or ~/.ai/directives/ (user)
Format: Markdown with YAML frontmatter
Operations: search, load, run, publish, delete, create, update

script

Location: .ai/scripts/ (project) or ~/.ai/scripts/ (user)
Format: Python (.py)
Operations: search, load, run, publish, delete
Features: venv isolation, auto-install dependencies, lib imports, .env loading

knowledge

Location: .ai/knowledge/ (project) or ~/.ai/knowledge/ (user)
Format: Markdown with metadata
Operations: search, load, create, update, delete, link, publish

Sources

local - Search only in .ai/ directories
registry - Search only in Supabase registry
all - Search both local and registry (registry items marked separately)

Error Handling

All tools return consistent error responses:

{
  "error": "Description of what went wrong",
  "item_type": "directive",
  "message": "Human-readable message"
}

Troubleshooting

Import Errors

from kiwi_mcp import KiwiMCP
from kiwi_mcp.server import main

If imports fail:

Check Python version: python --version (need ≥3.11)
Reinstall: pip install -e .

No Supabase Connection

If registry is unavailable, local operations still work:

Search: Use source="local"
Load: Downloads from registry disabled
Execute: Local operations only

Slow Search

Use limit parameter to reduce results
Add more specific keywords
Filter by category/tags (see handler docs)

Contributing

Write tests first
Implement feature
Run: pytest tests/ -v --cov=kiwi_mcp
Check coverage >85%
Lint: ruff check kiwi_mcp/

License

MIT License - see LICENSE file

Support

Documentation: docs/ARCHITECTURE.md, docs/API.md
Examples: See quick start above
Issues: GitHub issues

Roadmap

GraphQL registry queries
Authentication/authorization
Webhooks and real-time updates
Web UI for management
Plugin system for custom handlers
Vector search with RAG

Kiwi MCP - Unified AI Agent Tools

Overview

Installation

Prerequisites

From Source

Dependencies

Quick Start

Initialize

Usage Examples

Search for Directives

Load a Script

Run a Directive

Publish to Registry

Tools Reference

search

load

execute

help

Configuration

Environment Variables

.env Files

Script Execution Features

Virtual Environment Isolation

Dependency Auto-Install

Shared Libraries

Output Management

Architecture

Project Structure

Testing

Run All Tests

Run Unit Tests Only

Coverage Report

Coverage Target

Development

Install Dev Dependencies

Code Quality

Running Locally

API Reference

Item Types

Sources

Error Handling

Troubleshooting

Import Errors

No Supabase Connection

Slow Search

Contributing

License

Support

Roadmap

Resources

Latest Blog Posts

MCP directory API