# @merabylabs/promptarchitect-mcp

[![npm version](https://img.shields.io/npm/v/@merabylabs/promptarchitect-mcp.svg)](https://www.npmjs.com/package/@merabylabs/promptarchitect-mcp)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)

A Model Context Protocol (MCP) server that refines your prompts using PromptArchitect's AI-powered prompt engineering. Simply pass your current prompt and get an improved version back.

**Works with:** Claude Desktop • VS Code (Copilot) • Cursor • Windsurf • Zed • JetBrains IDEs • Continue.dev • Cline

## ✨ Why PromptArchitect MCP?

### 🎯 Workspace-Aware Refinement

Unlike generic prompt tools, PromptArchitect understands **your project context**. When refining prompts, it considers:

- **Your tech stack** — React, Node, Python, or whatever you're building with
- **Project structure** — File organization, naming conventions, architecture patterns  
- **Dependencies** — Libraries and frameworks from your package.json/requirements.txt
- **Your original request** — Ensures refined prompts stay aligned with your actual goal

This means prompts are tailored to **your specific codebase**, not generic boilerplate.

### 🚀 Key Benefits

- **No API key required** — Free to use, powered by PromptArchitect backend
- **Works in your IDE** — Integrates with your existing workflow via MCP
- **Context-aware** — Prompts that understand your project conventions
- **Iterative refinement** — Keep improving until it's perfect

## Features

### 🛠️ Tools

| Tool | Description |
|------|-------------|
| `refine_prompt` | Improve your current prompt based on feedback and your workspace context |
| `analyze_prompt` | Evaluate prompt quality with scores and improvement suggestions |
| `generate_prompt` | Transform a raw idea into a well-structured prompt tailored to your project |

### 📦 Resources

- **Template Library**: Reference templates for coding, writing, research, and analysis tasks
- **Category Collections**: Browse templates by category for inspiration

## Installation

```bash
npm install @merabylabs/promptarchitect-mcp
```

Or install globally:

```bash
npm install -g @merabylabs/promptarchitect-mcp
```

## Usage

PromptArchitect MCP server works with any IDE or application that supports the [Model Context Protocol](https://modelcontextprotocol.io). Below are configuration examples for popular editors.

> **No API key required!** The MCP server uses the PromptArchitect backend API, so you don't need your own Gemini API key.

---

### Claude Desktop

Add to your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"]
    }
  }
}
```

---

### VS Code (GitHub Copilot)

Add to your VS Code `settings.json` (Cmd/Ctrl+Shift+P → "Preferences: Open Settings (JSON)"):

```json
{
  "github.copilot.chat.mcp.servers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"]
    }
  }
}
```

---

### Cursor

Add to your Cursor MCP settings:
- **macOS/Linux**: `~/.cursor/mcp.json`
- **Windows**: `%USERPROFILE%\.cursor\mcp.json`
- Or via: Settings → MCP

```json
{
  "mcpServers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"]
    }
  }
}
```

📖 [Cursor MCP Documentation](https://docs.cursor.com/advanced/model-context-protocol)

---

### Windsurf (Codeium)

Add to your Windsurf MCP configuration:
- **macOS/Linux**: `~/.codeium/windsurf/mcp_config.json`
- **Windows**: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`

```json
{
  "mcpServers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"]
    }
  }
}
```

📖 [Windsurf MCP Documentation](https://docs.codeium.com/windsurf/mcp)

---

### Zed

Add to your Zed settings:
- **macOS**: `~/.config/zed/settings.json`
- **Linux**: `~/.config/zed/settings.json`

```json
{
  "context_servers": {
    "promptarchitect": {
      "command": {
        "path": "npx",
        "args": ["@merabylabs/promptarchitect-mcp"]
      },
      "settings": {}
    }
  }
}
```

📖 [Zed MCP Documentation](https://zed.dev/docs/assistant/model-context-protocol)

---

### JetBrains IDEs

Works with **IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand, RubyMine, CLion, DataGrip, Rider, Android Studio**.

1. Install the **MCP Client** plugin from JetBrains Marketplace
2. Go to Settings → Tools → MCP Servers
3. Add a new server with this configuration:

```json
{
  "mcpServers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"]
    }
  }
}
```

Or add to `.idea/mcp.json` in your project.

📖 [JetBrains MCP Plugin](https://plugins.jetbrains.com/plugin/mcp-client)

---

### Continue.dev

Add to your Continue configuration:
- **Global**: `~/.continue/config.json`
- **Project**: `.continue/config.json`

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@merabylabs/promptarchitect-mcp"]
        }
      }
    ]
  }
}
```

📖 [Continue MCP Documentation](https://docs.continue.dev/customize/model-context-protocol)

---

### Cline (VS Code Extension)

Open Cline Settings → MCP Servers, or edit `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "promptarchitect": {
      "command": "npx",
      "args": ["@merabylabs/promptarchitect-mcp"],
      "disabled": false
    }
  }
}
```

📖 [Cline MCP Documentation](https://github.com/cline/cline#mcp-support)

---

### Other MCP-Compatible Applications

Any application supporting MCP can use this server. The standard configuration is:

| Property | Value |
|----------|-------|
| Command | `npx` |
| Args | `["@merabylabs/promptarchitect-mcp"]` |

For global installation, use `promptarchitect-mcp` as the command after running:
```bash
npm install -g @merabylabs/promptarchitect-mcp
```

---

### Programmatic Usage

```typescript
import { refinePrompt, analyzePrompt } from '@promptarchitect/mcp-server';

// Refine an existing prompt
const result = await refinePrompt({
  prompt: 'Write code to sort an array',
  feedback: 'Make it more specific about language and edge cases',
});

console.log(result.refinedPrompt);
// => "Write a TypeScript function that sorts an array of numbers..."

// Analyze prompt quality
const analysis = await analyzePrompt({
  prompt: 'Help me with my code',
});
console.log(analysis.scores); // { overall: 45, clarity: 50, ... }
console.log(analysis.suggestions); // ["Be more specific about...", ...]
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `LOG_LEVEL` | No | Logging level: `debug`, `info`, `warn`, `error`. Default: `info` |

## Tool Reference

### refine_prompt

Improve an existing prompt based on feedback. **This is the primary tool.**

**Input:**
```json
{
  "prompt": "Write code",
  "feedback": "Make it more specific and add examples",
  "preserveStructure": true
}
```

**Output:**
```json
{
  "refinedPrompt": "Write a TypeScript function that...",
  "changes": ["Added specificity", "Included example"],
  "metadata": {
    "originalWordCount": 2,
    "refinedWordCount": 45
  }
}
```

### analyze_prompt

Evaluate prompt quality and get improvement suggestions.

**Input:**
```json
{
  "prompt": "You are a helpful assistant. Help me write code."
}
```

**Output:**
```json
{
  "scores": {
    "overall": 65,
    "clarity": 70,
    "specificity": 50,
    "structure": 60,
    "actionability": 80
  },
  "suggestions": [
    "Add more specific details about the code",
    "Include examples of expected output"
  ],
  "strengths": ["Clear action verb"],
  "weaknesses": ["Lacks specificity"]
}
```

### generate_prompt

Transform a raw idea into a well-structured prompt.

**Input:**
```json
{
  "idea": "Create a code review assistant",
  "template": "coding",
  "context": "For TypeScript projects"
}
```

**Output:**
```json
{
  "prompt": "You are a senior code reviewer...",
  "metadata": {
    "template": "coding",
    "wordCount": 150,
    "hasStructure": true
  }
}
```

## Development

### Building

```bash
npm install
npm run build
```

### Testing

```bash
npm test
```

### Running Locally

```bash
npm start
```

## Architecture

```
mcp-server/
├── src/
│   ├── tools/           # MCP tools (refine, analyze, generate)
│   ├── resources/       # Template library for reference
│   ├── utils/           # Gemini client, logger
│   ├── server.ts        # MCP server configuration
│   ├── cli.ts           # CLI entry point
│   └── index.ts         # Main exports
└── examples/            # Configuration examples
```

## License

Proprietary - © 2025 Meraby Labs. All rights reserved.

This software is provided for use exclusively with the PromptArchitect service. Unauthorized copying, modification, distribution, or use outside the intended scope is prohibited.

## Related

- [PromptArchitect](https://promptarchitectlabs.com/) - Full web application
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) - SDK used by this server