README.md

---
title: MaTableGPT MCP
emoji: 🔬
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# MaTableGPT MCP Service

[![HuggingFace Spaces](https://img.shields.io/badge/🤗-HuggingFace%20Spaces-blue)](https://huggingface.co/spaces)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green)](https://modelcontextprotocol.io/)

**GPT-based Table Data Extractor from Materials Science Literature**

A Model Context Protocol (MCP) service that extracts structured catalyst performance data from HTML tables in materials science publications.

## 🌟 Features

### Table Representation
- **HTML to TSV**: Convert HTML tables to tab-separated format with preserved structure
- **HTML to JSON**: Convert HTML tables to nested JSON format
- **Table Splitting**: Break down complex tables with multiple headers into simpler components

### GPT-based Extraction
- **Zero-shot**: Multi-step questioning approach without examples
- **Few-shot**: Guided extraction with input/output examples
- **Fine-tuned**: Use pre-trained specialized models

### Session Management
- Track multiple table processing workflows
- Store representations and extractions
- Export session data for analysis

## 🚀 Quick Start (HuggingFace Space SSE Mode)

This service runs as a **pure MCP SSE server** on HuggingFace Space, accessible via SSE endpoint.

**SSE Endpoint**: `https://your-space-name.hf.space/sse`

### Connect from Cursor/Claude Desktop

```json
{
  "mcpServers": {
    "matablgpt": {
      "url": "https://your-space-name.hf.space/sse"
    }
  }
}
```

## 📦 Installation

### Prerequisites
- Python 3.8+
- OpenAI-compatible API key (for GPT extraction)

### Local Installation

```bash
# Clone or copy the mcp_output folder
cd mcp_output

# Create virtual environment
python -m venv venv

# Activate (Windows)
venv\Scripts\activate
# Activate (Unix/Mac)
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set API configuration (use your third-party API service info)
# Windows PowerShell
$env:LLM_API_KEY = "your_api_key"
$env:LLM_API_BASE = "https://api.your-service.com/v1"
$env:LLM_MODEL = "gpt-4-turbo-preview"

# Windows CMD
set LLM_API_KEY=your_api_key
set LLM_API_BASE=https://api.your-service.com/v1
set LLM_MODEL=gpt-4-turbo-preview

# Unix/Mac
export LLM_API_KEY=your_api_key
export LLM_API_BASE=https://api.your-service.com/v1
export LLM_MODEL=gpt-4-turbo-preview
```

## 🔑 Environment Variables

This service supports third-party API services (reverse proxy, OneAPI, API aggregators, etc.)

| Variable | Required | Description |
|----------|----------|-------------|
| `LLM_API_KEY` | ✅ Yes | Your API key from the service provider |
| `LLM_API_BASE` | ✅ Yes | API base URL, e.g., `https://api.your-service.com/v1` |
| `LLM_MODEL` | ❌ No | Model name (default: gpt-4-turbo-preview) |

**Alternative variable names (also supported):**
| Variable | Description |
|----------|-------------|
| `OPENAI_API_KEY` | Alternative to LLM_API_KEY |
| `OPENAI_API_BASE` | Alternative to LLM_API_BASE |
| `OPENAI_MODEL` | Alternative to LLM_MODEL |

## 🚀 Usage

### Start MCP Server (SSE mode - Default for HuggingFace Space)

```bash
# Default: SSE mode on port 7860
python start_mcp.py

# Custom port
python start_mcp.py --mode sse --port 8080
```

### Start MCP Server (stdio mode - For local Cursor integration)

```bash
python start_mcp.py --mode stdio
```

## 🔧 MCP Tools Reference

### Session Management

| Tool | Description |
|------|-------------|
| `create_session` | Create a new extraction session |
| `get_session_data` | Retrieve all data from a session |

### Table Processing

| Tool | Description |
|------|-------------|
| `html_to_tsv_representation` | Convert HTML table to TSV format |
| `html_to_json_representation` | Convert HTML table to JSON format |
| `analyze_table_structure` | Analyze table structure (headers, merged cells) |
| `split_complex_table` | Split tables with multiple internal headers |

### Data Extraction

| Tool | Description |
|------|-------------|
| `extract_catalyst_data_zero_shot` | Extract using zero-shot GPT |
| `extract_catalyst_data_few_shot` | Extract with example pairs |
| `extract_catalyst_data_fine_tuned` | Extract using fine-tuned model |
| `batch_extract_tables` | Extract from multiple tables in batch |

### Follow-up & Refinement

| Tool | Description |
|------|-------------|
| `apply_follow_up_questions` | Refine extraction with iterative Q&A (from original MaTableGPT) |

### Evaluation

| Tool | Description |
|------|-------------|
| `evaluate_extraction` | Compute Structure F1 Score and Value Accuracy |
| `validate_extraction_result` | Validate extraction against schema |

### Utilities

| Tool | Description |
|------|-------------|
| `list_performance_types` | List supported catalyst performance types |
| `get_extraction_code_template` | Get Python code for local extraction |
| `get_environment_requirements` | Get setup requirements |

## 📋 Supported Performance Types

The following catalyst performance types can be extracted:

- `overpotential`, `tafel_slope`, `Rct`, `stability`, `Cdl`
- `onset_potential`, `current_density`, `potential`, `TOF`, `ECSA`
- `water_splitting_potential`, `mass_activity`, `exchange_current_density`
- `Rs`, `specific_activity`, `onset_overpotential`, `BET`, `surface_area`
- `loading`, `apparent_activation_energy`

## 🔄 Workflow Example

### 1. Create a session

```python
result = create_session()
session_id = result["session_id"]
```

### 2. Convert HTML table to representation

```python
html = "<table>...</table>"
tsv = html_to_tsv_representation(
    html_table=html,
    title="Table 1: Catalyst Performance",
    caption="OER performance in 1M KOH",
    session_id=session_id,
    table_name="table1"
)
```

### 3. Extract catalyst data

```python
extraction = extract_catalyst_data_zero_shot(
    table_representation=tsv["representation"],
    session_id=session_id,
    table_name="table1"
)
```

### 4. Validate and export

```python
validation = validate_extraction_result(extraction["extraction"])
session_data = get_session_data(session_id)
```

## 🐳 Docker Deployment

### Build image

```bash
docker build -t matablgpt-mcp .
```

### Run container (SSE mode)

```bash
docker run -p 7860:7860 \
    -e LLM_API_KEY=your_key \
    -e LLM_API_BASE=https://api.your-service.com/v1 \
    matablgpt-mcp
```

## 🤗 HuggingFace Spaces Deployment

1. Create a new Space with **Docker SDK**
2. Upload all files from `mcp_output/`
3. Add secrets in Space settings:
   - `LLM_API_KEY`: Your API key
   - `LLM_API_BASE`: Your API base URL (e.g., `https://api.your-service.com/v1`)
   - `LLM_MODEL`: (Optional) Model name
4. Space will auto-build and deploy the MCP SSE service
5. Connect via: `https://your-space-name.hf.space/sse`

## 📝 MCP Client Configuration

### For Cursor (SSE mode - HuggingFace Space)

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "matablgpt": {
      "url": "https://your-space-name.hf.space/sse"
    }
  }
}
```

### For Cursor (stdio mode - Local)

```json
{
  "mcpServers": {
    "matablgpt": {
      "command": "python",
      "args": ["F:/Material_Agent/MaTableGPT/mcp_output/start_mcp.py", "--mode", "stdio"],
      "env": {
        "LLM_API_KEY": "your_key",
        "LLM_API_BASE": "https://api.your-service.com/v1"
      }
    }
  }
}
```

### For Claude Desktop

```json
{
  "mcpServers": {
    "matablgpt": {
      "url": "https://your-space-name.hf.space/sse"
    }
  }
}
```

## 📄 Output Format

Extracted data follows this JSON schema:

```json
{
  "catalyst_name": {
    "overpotential": {
      "electrolyte": "1.0 M KOH",
      "reaction_type": "OER",
      "value": "230 mV",
      "current_density": "10 mA/cm²"
    },
    "tafel_slope": {
      "electrolyte": "1.0 M KOH",
      "reaction_type": "OER",
      "value": "45 mV/dec"
    }
  }
}
```

## 🙏 Acknowledgments

Based on [MaTableGPT](https://github.com/KIST-CSRC/MaTableGPT) - GPT-based Table Data Extractor from Materials Science Literature.

## 📜 License

MIT License