npm package: @issuecapture/mcp-server
Description: MCP server for AI-assisted IssueCapture widget installation
Author: IssueCapture
Latest version: 1.0.4

# IssueCapture MCP Server

Model Context Protocol (MCP) server for AI-assisted IssueCapture widget installation.

## What is This?

This MCP server enables AI assistants (Claude Code, Cursor, VS Code Copilot, Zed, etc.) to automatically install and configure the IssueCapture widget into your web applications with intelligent placement decisions.

## Features

- 🔍 **Automatic Framework Detection** - Detects Next.js, React, Vue, Angular, Svelte, or Vanilla JS
- 🎯 **Intelligent Placement** - Analyzes your codebase to find the best widget location
- 📝 **Code Generation** - Generates framework-specific installation code
- 🚀 **One-Command Installation** - Complete setup with a single command
- 📚 **Built-in Documentation** - Access guides and references as MCP resources

## Installation (30 seconds)

**No downloads required!** Uses `npx` to run directly from npm.

### Quick Setup

**1. Add to your AI tool's MCP config:**

<details>
<summary><b>Claude Code</b> (~/.config/claude-code/mcp.json)</summary>

```json
{
  "mcpServers": {
    "issuecapture": {
      "command": "npx",
      "args": ["-y", "@issuecapture/mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b> (.cursor/mcp.json in your project)</summary>

```json
{
  "mcpServers": {
    "issuecapture": {
      "command": "npx",
      "args": ["-y", "@issuecapture/mcp-server"]
    }
  }
}
```

</details>

<details>
<summary><b>VS Code + Copilot</b> (.vscode/mcp.json in your project)</summary>

```json
{
  "mcp": {
    "servers": {
      "issuecapture": {
        "command": "npx",
        "args": ["-y", "@issuecapture/mcp-server"]
      }
    }
  }
}
```

**Or** add to User Settings JSON (Cmd/Ctrl+Shift+P → "Preferences: Open User Settings (JSON)"):

```json
{
  "mcp.servers": {
    "issuecapture": {
      "command": "npx",
      "args": ["-y", "@issuecapture/mcp-server"]
    }
  }
}
```

**One-Click Install:**

[![Install in VS Code](https://img.shields.io/badge/VS%20Code-Install-blue?logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?config=%7B%22mcp%22%3A%7B%22servers%22%3A%7B%22issuecapture%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40issuecapture%2Fmcp-server%22%5D%7D%7D%7D%7D)

</details>

<details>
<summary><b>Zed</b> (~/.config/zed/settings.json)</summary>

```json
{
  "context_servers": {
    "issuecapture": {
      "command": "npx",
      "args": ["-y", "@issuecapture/mcp-server"]
    }
  }
}
```

</details>

**2. Restart your editor**

**3. Done!** 🎉

> 📖 See [SETUP.md](./SETUP.md) for detailed setup guides per editor.

## Usage

### Quick Installation

Ask your AI assistant:

```
"Install IssueCapture widget into my project"
```

The AI will:

1. Detect your framework
2. Analyze your codebase
3. Recommend placement strategy
4. Generate installation code
5. Apply changes (with your approval)

### Step-by-Step Installation

You can also use individual tools for more control:

1. **Detect Framework**

   ```
   Use issuecapture_detect to identify my framework
   ```

2. **Analyze Codebase**

   ```
   Use issuecapture_analyze to find existing feedback buttons
   ```

3. **Generate Code**

   ```
   Use issuecapture_generate to create installation code
   ```

4. **Apply Changes**
   ```
   Use issuecapture_apply to create the files
   ```

## Available Tools

### `issuecapture_install`

Complete installation wizard. Detects framework, analyzes codebase, and generates code.

**Parameters:**

- `projectRoot` (string, required) - Absolute path to project
- `apiKey` (string, required) - IssueCapture API key
- `interactive` (boolean, optional) - Enable interactive mode (default: true)

**Example:**

```
issuecapture_install with projectRoot="/path/to/project" and apiKey="ic_abc123"
```

### `issuecapture_detect`

Detect web framework and project structure.

**Parameters:**

- `projectRoot` (string, required) - Absolute path to project

**Returns:**

- Framework type
- Confidence score
- TypeScript detection
- SSR detection
- Build tool

### `issuecapture_analyze`

Analyze codebase for existing feedback elements.

**Parameters:**

- `projectRoot` (string, required) - Absolute path to project
- `framework` (string, required) - Framework type (from detect tool)

**Returns:**

- Existing feedback elements
- Layout files
- Placement recommendations

### `issuecapture_generate`

Generate installation code for specific framework.

**Parameters:**

- `framework` (string, required) - Framework type
- `placement` (string, required) - "auto", "existing", or "custom"
- `apiKey` (string, required) - IssueCapture API key
- `projectRoot` (string, optional) - Absolute project path (improves path selection like `src/app` vs `app`)
- `typescript` (boolean, optional) - Use TypeScript (default: false)
- `existingElement` (object, optional) - Existing element details

**Returns:**

- Files to create/modify
- Environment variables
- Installation instructions

### `issuecapture_apply` ⚠️ **DESTRUCTIVE**

Apply generated code to project. **This tool creates and modifies files in your project.**

**Security Notes:**

- ✅ **Safe**: Path traversal protection prevents writing outside project root
- ✅ **Safe**: Creates new files (hooks, snippets) instead of overwriting existing code
- ⚠️ **Caution**: Modifies `.env.local` files to add API keys
- ⚠️ **Caution**: Writes files to disk - review generated code before applying

**Parameters:**

- `projectRoot` (string, required) - Absolute path to project
- `files` (array, required) - Files to create/modify
- `envVars` (array, optional) - Environment variables to add

**Returns:**

- Success/error status for each file

**Best Practice:** Always review the output from `issuecapture_generate` before calling `issuecapture_apply`.

## Available Resources

Access documentation directly through MCP:

- `issuecapture://docs/quick-start` - Quick start guide
- `issuecapture://docs/api-key` - API key setup
- `issuecapture://docs/frameworks` - Supported frameworks
- `issuecapture://docs/configuration` - Widget configuration

## Supported Frameworks

- ✅ Next.js (App Router & Pages Router)
- ✅ React (Vite & Create React App)
- ✅ Vue 3
- ✅ Angular 14+
- ✅ Svelte / SvelteKit
- ✅ Vanilla JavaScript

## How It Works

1. **Framework Detection**
   - Analyzes `package.json` dependencies
   - Checks for config files (`next.config.js`, `vite.config.ts`, etc.)
   - Examines file structure patterns
   - Detects TypeScript, SSR, and build tools

2. **Codebase Analysis**
   - Searches for existing feedback buttons/links
   - Scores matches by location and semantic meaning
   - Finds layout and navigation components

3. **Intelligent Placement**
   - Recommends using existing elements (high confidence)
   - Suggests auto-positioned button (no existing elements)
   - Proposes custom triggers (custom layouts)

4. **Code Generation**
   - Generates framework-specific code
   - Includes proper imports and types
   - Handles SSR (for Next.js, SvelteKit)
   - Adds environment variables

## Getting Your API Key

1. Sign up at https://issuecapture.com
2. Go to Settings in the dashboard
3. Copy your API key from the "Widget Installation" section

## Examples

### Next.js with Existing Button

```
Detected: Next.js App Router with TypeScript
Found: "Feedback" button in app/components/Navbar.tsx
Recommendation: Use existing element (85% confidence)
```

Generated code will use the existing button as the widget trigger.

### React with No Existing Elements

```
Detected: React + Vite with TypeScript
Found: No existing feedback elements
Recommendation: Auto-positioned button (recommended)
```

Generated code will add a floating button in the bottom-right corner.

### Vanilla JS with Custom Layout

```
Detected: Vanilla JavaScript
Found: Navigation menu structure
Recommendation: Custom trigger in navigation
```

Generated code will add a button to your existing navigation.

## Development

### Prerequisites

- Node.js 18+
- pnpm (or npm)

### Build

```bash
cd mcp-server
pnpm install
pnpm build
```

### Local Testing

```bash
pnpm start
```

Then configure your MCP client to use the local build:

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

### Debugging with MCP Inspector

The MCP Inspector provides a visual interface to test and debug your server:

```bash
# Run the inspector
npx @modelcontextprotocol/inspector node dist/index.js

# Or test with npx distribution
npx @modelcontextprotocol/inspector npx -y @issuecapture/mcp-server
```

This opens a web UI where you can:

- Inspect available tools and resources
- Test tool calls with different parameters
- View request/response logs
- Debug connection issues

### Docker Support

For locked-down environments or containerized deployments:

**Dockerfile:**

```dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY dist ./dist
CMD ["node", "dist/index.js"]
```

**Build and run:**

```bash
docker build -t issuecapture-mcp .
docker run -i issuecapture-mcp
```

**MCP config for Docker:**

```json
{
  "mcpServers": {
    "issuecapture": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "issuecapture-mcp"]
    }
  }
}
```

## Support

- Documentation: https://docs.issuecapture.com
- GitHub: https://github.com/issuecapture/mcp-server
- Discord: https://discord.gg/issuecapture
- Email: support@issuecapture.com

## License

MIT

## About IssueCapture

IssueCapture is a modern bug reporting widget that integrates directly with Jira. Features include:

- 📸 Screenshot capture with annotation tools
- 🤖 10 AI-powered features (triaging, sentiment, OCR, etc.)
- 💰 Credits-based pricing (pay per issue, not per seat)
- 🎨 Fully customizable appearance
- 🔒 Enterprise-grade security
- 🚀 40KB initial bundle (industry-leading performance)

Learn more at https://issuecapture.com