npm package: @shaykec/ai-native-templates
Description: MCP server for AI-Native Engineer templates
Author: shaykec
Latest version: 1.0.0

# AI-Native Templates MCP Server

MCP server that provides AI-Native Engineer templates for syncing to your projects.

## Overview

This MCP server is a **pure data provider**. It fetches templates from GitHub and returns them with `llmInstructions` that guide the AI agent on how to handle each file. The agent (not the MCP) performs all file operations.

## Prerequisites

- **Node.js 20+**
- **gh CLI** installed and authenticated:

```bash
# Install gh CLI
brew install gh  # macOS
# or see https://cli.github.com/

# Authenticate
gh auth login
```

## Installation

### Via npx (recommended)

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ai-native-templates": {
      "command": "npx",
      "args": ["@shaykec/ai-native-templates"]
    }
  }
}
```

### Local development

```bash
cd mcp-server
npm install
npm run build
```

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ai-native-templates": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}
```

## Usage

### Single Tool: `templates`

This MCP exposes one tool with two modes:

#### List Templates

```
templates({ mode: "list" })
```

Returns array of available templates with descriptions:

```json
{
  "templates": [
    { "path": "templates/root/AGENTS.md", "destPath": "AGENTS.md", "description": "Core AI agent instructions." },
    { "path": "templates/cursor-rules/security.mdc", "destPath": ".cursor/rules/security.mdc", "description": "Security rules." }
  ]
}
```

#### Sync Templates

```
templates({ mode: "sync" })
```

Returns all templates with content and handling instructions:

```json
{
  "templates": [
    {
      "destPath": "AGENTS.md",
      "content": "# AGENTS.md - AI Agent Instructions...",
      "llmInstructions": {
        "purpose": "Core AI agent instructions.",
        "action": "merge",
        "preserve": ["Quick Reference Commands", "Project Overview"],
        "update": ["Critical Rules", "Workflows"],
        "hints": "Keep project-specific content, update process sections."
      }
    }
  ],
  "latestCommit": "abc1234",
  "globalInstructions": "For each template..."
}
```

## llmInstructions Actions

| Action | Behavior |
|--------|----------|
| `create-if-missing` | Only create file if it doesn't exist |
| `overwrite` | Replace file entirely with template |
| `merge` | Use `preserve`/`update` arrays to intelligently merge |

## Templates Included

- **Root docs:** AGENTS.md, CONTRIBUTING.md, SECURITY.md, TESTING.md
- **Cursor rules:** always.mdc, security.mdc, testing.mdc, code-style.mdc, architecture.mdc
- **Scripts:** start-issue.sh, finish-issue.sh, check-ci.sh, setup.sh, etc.
- **GitHub:** PR template, issue templates, CI workflows
- **Knowledge:** DECISIONS.md, KNOWN_ISSUES.md, LESSONS_LEARNED.md

## How It Works

1. Templates are stored in `shayke-cohen/native-agent` GitHub repo
2. MCP fetches templates via `gh api` (uses your existing GitHub auth)
3. Templates are cached for 1 hour
4. Agent receives templates + llmInstructions
5. Agent reads existing files, applies merge logic, writes files
6. No file system access needed by MCP - agent handles everything

## Agent Workflow

When a user asks to sync templates:

1. Agent calls `templates({ mode: "sync" })`
2. For each template in response:
   - Read existing file at `destPath` (if any)
   - Apply `action` from `llmInstructions`
   - Write file using agent's file tools
3. Report: X created, Y updated, Z skipped
4. Remind user: `chmod +x scripts/*.sh`

## Source Repository

Templates: https://github.com/shayke-cohen/native-agent

## Related

- [ai-tester](https://github.com/shayke-cohen/ai-tester) - AI-powered testing MCP server