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:

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

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

Usage Examples

Search for Directives

Response:

Load a Script

Response:

Run a Directive

Response:

Publish to Registry

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:

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:

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:

Examples:

help

Get usage guidance, examples, and troubleshooting.

Parameters:

• topic (optional): Specific topic for help

Returns: JSON with help text

Examples:

Configuration

Environment Variables

.env Files

Environment variables can be loaded from hierarchical .env files:

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

Shared Libraries

Scripts can import from shared library modules:

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

Project Structure

Testing

Run All Tests

Run Unit Tests Only

Coverage Report

Coverage Target

• Goal: >85% code coverage

• Current: ✅ Achieved

Development

Install Dev Dependencies

Code Quality

Running Locally

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:

Troubleshooting

Import Errors

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