Skip to main content
Glama
leolilley

Kiwi MCP

by leolilley
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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:

  1. Check Python version: python --version (need ≥3.11)

  2. 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

  1. Write tests first

  2. Implement feature

  3. Run: pytest tests/ -v --cov=kiwi_mcp

  4. Check coverage >85%

  5. 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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/leolilley/kiwi-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server