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

# AI-Native Templates MCP Server

> **Note:** This MCP server is **optional/advanced**. Most users should use the simpler curl-based approach instead.

## Do You Need This?

**Use curl scripts (recommended for most users):**
```bash
# Install skills
curl -sL https://raw.githubusercontent.com/shayke-cohen/ai-native-engineer/main/templates/scripts/install-skill.sh | bash -s -- --all

# Install templates
curl -sL https://raw.githubusercontent.com/shayke-cohen/ai-native-engineer/main/templates/scripts/install-templates.sh | bash -s -- --all
```

Or tell your AI agent:
```
Read https://raw.githubusercontent.com/shayke-cohen/ai-native-engineer/main/SKILL.md and set up my project
```

**Use this MCP server when you need:**
- CI/CD integration with programmatic access
- Custom automation scripts that need template data
- IDE/tool integration beyond Cursor
- Real-time template fetching without shell scripts

---

## 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-engineer": {
      "command": "npx",
      "args": ["@shaykec/ai-native-engineer"]
    }
  }
}
```

### Local development

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

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ai-native-engineer": {
      "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/ai-native-engineer` 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`

## MCP vs Curl Scripts Comparison

| Feature | Curl Scripts | MCP Server |
|---------|-------------|------------|
| **Setup** | Zero setup | Requires npm + gh CLI |
| **Authentication** | None needed | Needs `gh auth login` |
| **Use in Cursor** | Agent reads SKILL.md | Agent calls MCP tool |
| **Offline use** | Downloads files | Requires live connection |
| **CI/CD friendly** | Yes (bash) | Yes (programmatic API) |
| **Update checking** | Via `--check-updates` | Returns `latestCommit` |
| **Smart merge** | Downloads as `.new` | Returns `llmInstructions` |

**Recommendation:** Start with curl scripts. Only add MCP if you need programmatic access.

## Source Repository

Templates: https://github.com/shayke-cohen/ai-native-engineer

## Related

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