@infactory/infactory-mcp/README.md

MCP server that implements the Infactory Quickstart guide tools using the latest MCP SDK.

# Infactory MCP Desktop Extension (DXT)

A Desktop Extension (DXT) that provides seamless access to Infactory's data analysis and API generation capabilities through Claude Desktop and other MCP clients.

## Overview

Infactory transforms articles, data, and archives into AI-ready formats that can be safely queried, cited and licensed. This DXT extension provides a complete workflow from data upload to API deployment.

## Features

- **Data Management**: Upload CSV files and manage datasources
- **Query Generation**: Auto-generate queries or create custom ones from natural language
- **API Deployment**: Publish query programs as live API endpoints
- **Chat Integration**: Explore data through conversational interfaces
- **Project Management**: Create and manage projects and teams

## Installation

### For Claude Desktop Users

1. Download the `.dxt` file from the releases
2. Open Claude Desktop
3. Go to Settings > Extensions
4. Click "Install from file" and select the `.dxt` file
5. Configure your Infactory API key in the extension settings (see Configuration section below)

### For Developers

```bash
# Clone the repository
git clone https://github.com/infactory/infactory-mcp.git
cd infactory-mcp

# Install dependencies
npm install

# Build the extension
npm run build

# Package as DXT
npm run dxt:pack
```

## Configuration

The extension requires configuration through the DXT user interface. After installation, you'll need to configure the following settings:

### Required Settings

- **Infactory API Key**: Your Infactory API key (get this from your [Infactory dashboard](https://app.infactory.ai))
  - This is a sensitive field that will be stored securely
  - Required for all API operations

### Optional Settings

- **Infactory API Base URL**: API base URL (defaults to `https://api.infactory.ai`)
  - Only change this if you're using a custom Infactory instance
  - Optional field with a sensible default

## Usage

### Quick Start Workflow

1. **Get Your Team ID**
   ```
   get_current_user
   ```

2. **Create a Project**
   ```
   create_project {"name": "My Analysis Project", "teamId": "team-..."}
   ```

3. **Upload CSV Data**
   ```
   upload_csv {"projectId": "proj-...", "filePath": "/path/to/data.csv", "datasourceName": "My Data"}
   ```

4. **Check Processing Status**
   ```
   get_datasource_status {"datasourceId": "ds-..."}
   ```

5. **Generate Queries**
   ```
   autogenerate_queries {"projectId": "proj-...", "count": 3}
   ```

6. **Run a Query**
   ```
   run_query_program {"projectId": "proj-...", "queryProgramId": "qp-..."}
   ```

7. **Create Custom Query**
   ```
   create_query_from_nl {"projectId": "proj-...", "question": "What is the average value by category?"}
   ```

8. **Publish as API**
   ```
   publish_query_program {"queryProgramId": "qp-..."}
   ```

### Available Tools

#### User & Project Management
- `get_current_user` - Get user profile and team information
- `create_project` - Create a new project
- `list_projects` - List all projects in a team
- `delete_project` - Delete a project

#### Data Management
- `upload_csv` - Upload a CSV file to create a datasource
- `get_datasource_status` - Check datasource processing status
- `delete_datasource` - Delete a datasource

#### Query Building
- `autogenerate_queries` - Generate starter queries based on data
- `create_query_from_nl` - Create query from natural language
- `list_query_programs` - List all query programs in a project

#### Query Execution
- `run_query_program` - Execute a query program
- `publish_query_program` - Publish query as live API

#### API Management
- `list_apis` - List deployed APIs
- `list_api_endpoints` - List API endpoints
- `call_live_api` - Call a live API endpoint

#### Chat & Explore
- `create_conversation` - Start a chat session
- `send_chat_message` - Send a message in chat
- `get_conversation_graph` - Get conversation interaction graph

## Development

### Prerequisites

- Node.js 18+
- npm or yarn
- TypeScript

### Setup

```bash
# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Validate DXT manifest
npm run dxt:validate
```

### Testing with MCP Inspector

```bash
# Run the MCP inspector to test tools
npm run inspector
```

### Building for Distribution

```bash
# Build and package as DXT
npm run dxt:pack
```

This creates a `.dxt` file that can be distributed and installed in Claude Desktop.

## Error Handling

The extension includes comprehensive error handling:

- **Timeout Management**: All API calls have appropriate timeouts
- **Configuration Validation**: Ensures required settings are present
- **Graceful Degradation**: Handles network and API errors gracefully
- **Detailed Logging**: Provides clear error messages for debugging

## Security

- API keys are stored securely using the host's secure storage
- Sensitive configuration fields are marked appropriately
- All API calls use HTTPS with proper authentication

## Troubleshooting

### Common Issues

1. **"NF_API_KEY not set"**
   - Ensure you've configured the "Infactory API Key" in the extension settings
   - Verify the key is valid in your Infactory dashboard
   - Check that the configuration was saved properly

2. **"Could not get default team ID"**
   - Check your API key permissions
   - Ensure you have access to at least one team

3. **File upload failures**
   - Verify the file path exists and is accessible
   - Check file size limits (typically 100MB)
   - Ensure the file is a valid CSV

4. **Query execution timeouts**
   - Large datasets may take longer to process
   - Consider breaking data into smaller chunks
   - Check your Infactory plan limits

### Debug Mode

Enable debug logging by setting the `DEBUG` environment variable:

```bash
DEBUG=* npm run dev
```

## Contributing

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

## License

MIT License - see LICENSE file for details.

## Support

- **Documentation**: [https://docs.infactory.ai](https://docs.infactory.ai)
- **Issues**: [GitHub Issues](https://github.com/infactory/infactory-mcp/issues)
- **Email**: [sean@infactory.ai](mailto:sean@infactory.ai)

## Changelog

### v0.8.0
- Initial DXT release
- Complete MCP server implementation
- All core Infactory functionality
- Comprehensive error handling and timeouts
- DXT packaging and validation