Metadata-Version: 2.4
Name: qpiai-quantum-agent-tools
Version: 0.1.0
Summary: Local MCP server exposing QpiAI Quantum SDK tools to agent harnesses
Project-URL: Company Website, https://www.qpiai.tech/
Project-URL: QCloud Platform, https://qcloud.qpiai.tech/
Project-URL: QpiAI-Quantum SDK, https://pypi.org/project/qpiai-quantum/
Author-email: QpiAI <info@qpiai.com>
License: Apache-2.0
License-File: LICENSE
Keywords: mcp,model-context-protocol,qpiai,quantum,quantum-computing,quantum-developers,quantum-research,quantum-simulation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.27
Requires-Dist: python-dotenv>=1.0
Requires-Dist: qpiai-quantum<2,>=0.1.35
Provides-Extra: dev
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# QpiAI Quantum Agent Tools

An MCP (Model Context Protocol) server that exposes the QpiAI Quantum SDK as tools for AI agent interfaces (such as OpenCode, Claude Desktop, and Cursor).

---

## Installation

Install the package directly:
```bash
pip install qpiai-quantum-agent-tools
```

---

## Configuration & Usage

Authentication requires a QpiAI API key. You can run the MCP server in one of two modes:

### 1. stdio Mode
The server runs directly as a subprocess managed by your AI agent interface. Configure it by adding the server definition under the environment settings in the client's configuration file.

#### Finding Your Config File
*   **OpenCode (`opencode.jsonc`):**
    *   **Windows:** `C:\Users\<username>\.config\opencode\opencode.jsonc`
    *   **Linux/macOS:** `~/.config/opencode/opencode.jsonc`
*   **Claude Desktop (`claude_desktop_config.json`):**
    *   **Windows:** `C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json`
    *   **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Other applications (e.g., Cursor, Cline, Roo Code):**
    *   Please search online or consult the application's documentation to find the location of its MCP configuration file.

#### OpenCode Configuration (`opencode.jsonc`)
```json
{
  "mcp": {
    "qpiai-quantum": {
      "type": "local",
      "command": ["qpiai-quantum-mcp"],
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      },
      "enabled": true
    }
  }
}
```

#### Claude Desktop Configuration (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "qpiai-quantum": {
      "command": "qpiai-quantum-mcp",
      "env": {
        "API_KEY": "your_qpiai_api_key_here"
      }
    }
  }
}
```

*Note: If the `qpiai-quantum-mcp` command is not on your system PATH, replace `"qpiai-quantum-mcp"` in the configurations above with the absolute path to the executable inside the Python environment where the package was installed (e.g., `"C:/path/to/venv/Scripts/qpiai-quantum-mcp.exe"` or `"/path/to/venv/bin/qpiai-quantum-mcp"`).*

---

### 2. HTTP Mode
For lower latency across multiple agent sessions, you can run the server as a persistent HTTP local server.

1. **Set the API Key** in the terminal where you will start the server:
   - **PowerShell:** `$env:API_KEY="your_qpiai_api_key_here"`
   - **Command Prompt:** `set API_KEY=your_qpiai_api_key_here`
   - **Linux/macOS:** `export API_KEY="your_qpiai_api_key_here"`
   - **Alternative:** Create a `.env` file containing `API_KEY=your_qpiai_api_key_here` in the directory where you run the server.

2. **Start the HTTP Server:**
   Run the following command in the terminal where the package was installed:
   ```bash
   qpiai-quantum-mcp --http
   ```
   *By default, the server starts on `http://127.0.0.1:8080/mcp`.*
   
   If the command is not recognized or not on your system PATH, you can run it via its absolute path or using Python:
   ```bash
   python -m qpiai_quantum_agent_tools.server --http
   ```

   Options:
   - `--port PORT` — Custom port (default: 8080)
   - `--host HOST` — Custom bind host (default: 127.0.0.1)

3. **Configure your client to connect to the URL:**
   - **OpenCode (`opencode.jsonc`):**
     ```json
     {
       "mcp": {
         "qpiai-quantum": {
           "type": "remote",
           "url": "http://127.0.0.1:8080/mcp",
           "enabled": true
         }
       }
     }
     ```
   - **Claude Desktop / Cursor:**
     ```json
     {
       "mcpServers": {
         "qpiai-quantum": {
           "url": "http://127.0.0.1:8080/mcp"
         }
       }
     }
     ```

---

## Tools

- `qpiai_health_check`: Reports SDK import status, active transport (stdio/http), and whether an API key is configured.
- `qpiai_verify_api_key`: Validates the configured key against QpiAI.
- `qpiai_get_user_details`: Retrieves the name and email of the authenticated user.
- `qpiai_list_compute_resources`: Lists available compute resources for the configured key.
- `qpiai_validate_qasm`: Performs basic OpenQASM sanity checks.
- `qpiai_submit_qasm_job`: Dry-runs by default; submits only when `run=true`.
- `qpiai_get_job_status`: Fetches job status by ID.
- `qpiai_get_job_result`: Fetches parsed job result data by ID.
- `qpiai_get_job_history`: Retrieves recent job submission history with optional status and period filtering.
- `qpiai_simulate_local`: Runs a local statevector simulator on custom circuit JSON.

---

## Example Prompts

- "Check whether QpiAI Quantum is configured."
- "List my available QpiAI compute resources."
- "Validate this Bell-state OpenQASM without submitting it."
- "Dry-run a submission of this QASM to QpiAI-QSV-Simulator with 1024 shots."
- "Submit this QASM with run=true after confirming the simulator and shot count."
