npm package: @kamiiiiii/ai-autocomplete-mcp
Description: MCP server for AI Autocomplete API - provides API documentation, types, and code generation for Claude Code
Author: Telepotch
Latest version: 1.1.0

# AI Autocomplete API - MCP Server

**Version 1.1.0** - Now with advanced API parameters and React integration guide!

Model Context Protocol (MCP) server for the AI Autocomplete API. Provides comprehensive API documentation, TypeScript types, code examples, and code generation tools directly to Claude Code and other MCP clients.

## What This Does

This MCP server enables Claude Code to automatically understand and implement the AI Autocomplete API without you having to manually provide documentation. When installed, Claude Code can:

- ✅ Read complete API specifications
- ✅ Access TypeScript type definitions
- ✅ View framework-specific examples (React, Vue, Node.js, Python)
- ✅ Generate integration code automatically
- ✅ Understand error codes and solutions
- ✅ Apply best practices for error handling and rate limiting

## Quick Start

### Installation with Claude Code CLI

```bash
claude mcp add ai-autocomplete npx @kamiiiiii/ai-autocomplete-mcp@latest
```

That's it! Claude Code will now have full context about the AI Autocomplete API.

### Manual Installation

1. **Install the package globally:**
   ```bash
   npm install -g @kamiiiiii/ai-autocomplete-mcp
   ```

2. **Configure Claude Desktop:**

   Edit `~/.config/claude/claude_desktop_config.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

   ```json
   {
     "mcpServers": {
       "ai-autocomplete": {
         "command": "ai-autocomplete-mcp"
       }
     }
   }
   ```

3. **Restart Claude Desktop**

## Usage

Once installed, you can ask Claude Code to implement the AI Autocomplete API in your project:

```
"Add AI autocomplete functionality to this React app"
```

Claude Code will:
1. Read the API specification from the MCP server
2. Understand the request/response formats
3. Generate the appropriate code with proper error handling
4. Apply best practices automatically

### Example Prompts

```
"Implement AI autocomplete with React hooks"
→ Claude generates a complete useAutocomplete hook

"Add autocomplete to this input field"
→ Claude integrates the API with your existing component

"Show me how to handle rate limiting"
→ Claude provides rate limit management code

"Generate Python integration code"
→ Claude creates Python code with proper SSE handling
```

## Available Resources

The MCP server provides these resources to Claude Code:

- **API Reference** (`ai-autocomplete://docs/api-reference`)
  - Complete endpoint documentation
  - Request/response formats
  - Rate limiting details

- **TypeScript Types** (`ai-autocomplete://docs/types`)
  - `AutocompleteRequest`
  - `AutocompleteStreamChunk`
  - `ErrorResponse`

- **Examples** (`ai-autocomplete://examples/*`)
  - TypeScript (React hooks, Node.js)
  - JavaScript (Vanilla)
  - Python (sync & async)
  - cURL

- **Error Reference** (`ai-autocomplete://docs/errors`)
  - All error codes
  - Causes and solutions

- **Best Practices** (`ai-autocomplete://docs/best-practices`)
  - Error handling patterns
  - Rate limit management
  - Caching strategies
  - Performance optimization

## Available Tools

### `generate_integration_code`

Generates ready-to-use integration code for various frameworks.

**Parameters:**
- `framework`: `'react' | 'vue' | 'vanilla' | 'node' | 'python'`
- `apiUrl`: API base URL (default: `https://ai-autocomplete-api.vercel.app`)
- `includeErrorHandling`: Include error handling (default: `true`)
- `includeRateLimit`: Include rate limit tracking (React only, default: `false`)

**Example:**
```
"Generate React integration code with rate limiting"
→ Claude uses the tool to create a complete React hook
```

## Verification

Check if the MCP server is working:

1. **In Claude Code:**
   ```
   "List available MCP resources"
   ```
   You should see `ai-autocomplete://docs/api-reference` and others.

2. **Test code generation:**
   ```
   "Generate a React hook for AI autocomplete"
   ```
   Claude should produce working code immediately.

## Troubleshooting

### MCP server not found

**Solution:**
```bash
# Verify installation
npm list -g @kamiiiiii/ai-autocomplete-mcp

# Reinstall if needed
npm install -g @kamiiiiii/ai-autocomplete-mcp
```

### Claude Code doesn't see the resources

**Solution:**
1. Check `claude_desktop_config.json` syntax (valid JSON)
2. Restart Claude Desktop completely
3. Check Claude Desktop logs for errors

### Permission denied

**Solution:**
```bash
# Make sure the binary is executable
chmod +x $(npm root -g)/@kamiiiiii/ai-autocomplete-mcp/dist/index.js
```

## What's New in v1.1.0

### Advanced API Parameters
- **maxTokens** (1-1000): Control completion length precisely
- **temperature** (0.0-1.0): Adjust creativity level
  - 0.0-0.3: Deterministic (code completion)
  - 0.4-0.7: Balanced (text completion)
  - 0.8-1.0: Creative (idea generation)
- **stopSequences**: Define custom stop conditions
- **context**: Provide additional context (language, fileType, etc.)

### Structured Error Responses
- Error code system (`VALIDATION_ERROR`, `RATE_LIMIT_EXCEEDED`, etc.)
- Detailed error messages with `details` field
- Request IDs for debugging (`X-Request-ID` header)
- `retryAfter` guidance for rate limit errors

### React Integration Guide
- **Production-ready patterns** addressing all common pitfalls
- Solutions to infinite loops (useRef pattern)
- Tab key handling (onKeyDownCapture)
- Composer state sync (useComposerRuntime)
- Height calculation with mirror element
- Scroll sync for long completions
- IME composition handling (Japanese/Chinese input)

This guide reduces implementation time from **2 hours to 20 minutes**!

## Development

### Local Testing

1. **Clone and build:**
   ```bash
   git clone https://github.com/Telepotch/ai-autocomplete-api.git
   cd ai-autocomplete-api/mcp
   npm install
   npm run build
   ```

2. **Test locally:**
   ```bash
   node dist/index.js
   ```
   (The MCP server communicates via stdio, so you won't see output directly)

3. **Link for local development:**
   ```bash
   npm link
   ```
   Then use `ai-autocomplete-mcp` in your Claude Desktop config.

### Project Structure

```
mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── resources/
│   │   ├── api-spec.ts       # API documentation
│   │   └── examples.ts       # Code examples
│   └── tools/
│       └── code-generator.ts # Code generation logic
├── dist/                     # Compiled JavaScript (generated)
├── package.json
└── README.md
```

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes (add examples, improve docs, etc.)
4. Submit a pull request

## License

MIT

## Related Links

- [AI Autocomplete API Documentation](https://ai-autocomplete-api.vercel.app)
- [Model Context Protocol Specification](https://modelcontextprotocol.io)
- [Claude Code Documentation](https://docs.claude.com/claude-code)

## Support

- **Issues:** [GitHub Issues](https://github.com/Telepotch/ai-autocomplete-api/issues)
- **Discussions:** [GitHub Discussions](https://github.com/Telepotch/ai-autocomplete-api/discussions)

---

**Built with ❤️ for the AI development community**