# XAPIHub MCP Extension for Cursor

A Model Context Protocol (MCP) extension that integrates XAPIHub API with Cursor IDE, allowing developers to interact with XAPIHub services directly from their development environment.

## Features

- 🔐 **User Authentication**: Get current user details from XAPIHub
- 🔗 **API Integration**: Direct connection to XAPIHub API endpoints
- ⚡ **Real-time Data**: Fetch live data from your XAPIHub organization
- 🛠️ **Developer Tools**: Built-in connection testing and diagnostics

## Installation

### Prerequisites

- Node.js 18+ 
- Cursor IDE with MCP support
- XAPIHub account and API token

### Setup

1. **Clone and Install Dependencies**
   ```bash
   git clone <your-repo-url>
   cd xapihub-mcp-extension
   npm install
   ```

2. **Configure Environment**
   ```bash
   cp env.example .env
   ```
   
   Edit `.env` with your XAPIHub credentials:
   ```env
   XAPIHUB_BASE_URL=https://api-dev.xapihub.io
   XAPIHUB_TOKEN=your_bearer_token_here
   ```

3. **Build the Extension**
   ```bash
   npm run build
   ```

4. **Install in Cursor**
   - Open Cursor IDE
   - Go to Extensions > Install from VSIX
   - Select the built extension package
   - Or configure MCP server manually (see below)

## Manual MCP Server Configuration

If you prefer to run the MCP server directly, add this to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "xapihub": {
      "command": "node",
      "args": ["path/to/your/dist/index.js"],
      "env": {
        "XAPIHUB_BASE_URL": "https://api-dev.xapihub.io",
        "XAPIHUB_TOKEN": "your_bearer_token_here"
      }
    }
  }
}
```

## Available Tools

### `get_current_user`
Retrieves current user details from XAPIHub API.

**Example Response:**
```json
{
  "success": true,
  "message": "Current user details retrieved successfully",
  "user": {
    "id": "user_id",
    "username": "username",
    "email": "user@example.com",
    "fullName": "John Doe",
    "organization": "org_id",
    "organizationType": "PREMIUM",
    "userType": "ORGANIZATION_OWNER",
    "userOrganizationAssociation": "OWNER",
    "organizationVisibility": "PUBLIC",
    "emailVerified": true,
    "readOnlyOrganization": false,
    "projectCount": 5,
    "userScopes": ""
  }
}
```

### `test_xapihub_connection`
Tests connectivity to XAPIHub API.

**Example Response:**
```json
{
  "success": true,
  "connected": true,
  "message": "Successfully connected to XAPIHub API"
}
```

## Usage in Cursor

Once installed, you can use the XAPIHub tools in several ways:

1. **Command Palette**: 
   - Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac)
   - Type "XAPIHub" to see available commands

2. **MCP Tools**:
   - Use the tools directly in your code context
   - Ask Cursor to "Get my XAPIHub user details"
   - Request "Test XAPIHub connection"

3. **Chat Integration**:
   - Ask Cursor: "What are my XAPIHub user details?"
   - Request: "Check if I'm connected to XAPIHub"

## Development

### Project Structure
```
src/
├── types/
│   └── xapihub.ts          # TypeScript type definitions
├── services/
│   └── xapihub-client.ts   # XAPIHub API client
├── server.ts               # MCP server implementation
└── index.ts                # Main entry point
```

### Scripts
- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Watch mode for development
- `npm run start` - Start the MCP server
- `npm test` - Run tests (when implemented)

### Adding New Tools

1. Define the tool in `src/server.ts`:
   ```typescript
   {
     name: 'your_tool_name',
     description: 'Tool description',
     inputSchema: {
       type: 'object',
       properties: {
         // Define input parameters
       },
       required: [],
     },
   }
   ```

2. Implement the handler:
   ```typescript
   case 'your_tool_name':
     return await this.handleYourTool(args);
   ```

3. Add the implementation method:
   ```typescript
   private async handleYourTool(args: any) {
     // Implementation
   }
   ```

## API Reference

The extension uses the XAPIHub REST API. Current endpoint:

- `GET /platform/1.0.0/users/current-user` - Get current user details

## Troubleshooting

### Common Issues

1. **Authentication Error**
   - Verify your `XAPIHUB_TOKEN` is correct and not expired
   - Check that the token has proper permissions

2. **Connection Failed**
   - Ensure `XAPIHUB_BASE_URL` is correct
   - Check network connectivity
   - Verify API endpoint is accessible

3. **MCP Server Not Starting**
   - Check Node.js version (18+ required)
   - Verify all dependencies are installed
   - Check console for error messages

### Debug Mode

To enable debug logging, set environment variable:
```bash
DEBUG=xapihub:* npm run start
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: [Create an issue](https://github.com/xapihub/cursor-mcp-extension/issues)
- Documentation: [XAPIHub Docs](https://docs.xapihub.io)
- Email: support@xapihub.io