# git-mcp-extensions

Kamiwaza extensions repository for kamiwazaai.

## Overview

This repository contains Kamiwaza platform extensions:
- **Apps** (`apps/`): Multi-service applications deployed to App Garden
- **Services** (`services/`): App Garden backend services (e.g., vector databases)
- **Tools** (`tools/`): MCP protocol servers deployed to Tool Shed

## Quick Start

### Prerequisites

- Docker and Docker Compose
- Python 3.10+
- [uv](https://github.com/astral-sh/uv) (recommended) or pip

### Setup

```bash
# Install development dependencies
make install

# List available extensions
make list
```

### Creating Extensions

```bash
# Create a new app
make new TYPE=app NAME=my-app

# Create a new service
make new TYPE=service NAME=service-milvus

# Create a new tool
make new TYPE=tool NAME=my-tool
```

### Development Workflow

```bash
# Build an extension
make build TYPE=app NAME=my-app

# Test an extension
make test TYPE=app NAME=my-app

# Validate all extensions
make validate

# Run full CI pipeline
make ci-pipeline
```

## Structure

```
git-mcp-extensions/
├── apps/                    # Multi-service applications
│   └── {app-name}/
│       ├── kamiwaza.json    # Extension metadata
│       ├── docker-compose.yml
│       ├── backend/
│       └── frontend/
├── services/                # App Garden backend services
│   └── {service-name}/
│       ├── kamiwaza.json
│       └── docker-compose.yml
├── tools/                   # MCP tool servers
│   └── {tool-name}/
│       ├── kamiwaza.json
│       ├── Dockerfile
│       └── src/
├── shared/                  # Shared libraries
│   ├── python/
│   └── typescript/
├── make/                    # Build system modules
├── scripts/                 # Build/test scripts
└── .ai/                     # AI assistant rules
```

## Extension Requirements

Each extension must have:
- `kamiwaza.json` with name, version, risk_tier
- `Dockerfile` for each service
- `docker-compose.yml` for local development
- Health endpoint at `GET /health` (apps only)

See `.ai/rules/architecture.md` for detailed requirements.

## Updating from Upstream

This repository was created from the Kamiwaza extensions template. To pull infrastructure updates:

```bash
# Update shared infrastructure (preserves apps/, services/, and tools/)
copier update --trust --skip-answered --defaults

# Review changes
git diff

# Commit updates
git add -A && git commit -m "Update infrastructure from upstream"
```

Tip: keep `.copier-answers.yml` committed so the template source is known. The flags above make the update non-interactive by reusing stored answers.

## Commands Reference

| Command | Description |
|---------|-------------|
| `make list` | List all extensions |
| `make new TYPE=app NAME=x` | Create new app |
| `make new TYPE=service NAME=x` | Create new service |
| `make new TYPE=tool NAME=x` | Create new tool |
| `make build TYPE=app NAME=x` | Build extension |
| `make test TYPE=app NAME=x` | Test extension |
| `make validate` | Validate all extensions |
| `make sync-compose` | Generate App Garden configs |
| `make build-registry` | Build extension registry |
| `make ci-pipeline` | Run full CI pipeline |

## Configuration

Docker images are prefixed with: `kamiwazaai/`

## GitHub Bootstrap

After creating the repo on GitHub, configure topics, branches, and protection rules:

```bash
# Interactive mode - prompts for each option
./scripts/setup-github-repo.sh

# Or use a config file for non-interactive setup
cp .github/repo-setup.yml.example .github/repo-setup.yml
# Edit config as needed, then run:
./scripts/setup-github-repo.sh
```

**What it configures:**
- Topics (`extensions`)
- Develop branch from main
- Branch naming rules (enforces `feature/*`, `fix/*`, etc.)
- Branch protection (PR reviews, status checks, force push blocking)

See `.github/repo-setup.yml.example` for all configuration options.

## License

Proprietary - kamiwazaai