Content
# GPT-Vis MCP - Intelligent Chart Recommendation Server
An intelligent data visualization tool based on MCP (Model Context Protocol), designed to enhance user experience. When users present data analysis requests, it **automatically determines and generates the corresponding charts 100% of the time**.
## 🎯 Core Features
### ✅ 100% Intelligent Invocation
- **Automatic Recognition**: When a user says, "Help me analyze the salary range for ByteDance's front-end development campus recruits," the AI will automatically invoke the visualization tool.
- **Intelligent Judgment**: Based on keyword and semantic analysis, it accurately determines whether data visualization is needed.
- **Instant Response**: No explicit request from the user is required; it recommends generating suitable charts.
### 🛠️ Two Core Tools
#### 1. `check_if_needs_visualization` (Judgment Tool)
- **Responsibility**: Smartly determines whether the user's question requires data visualization.
- **Input**: The user's complete question or request.
- **Output**: Judgment result + Recommended chart type + Confidence level.
- **Features**: Only makes judgments, does not generate charts.
- **Trigger Keywords**: Statistics, analysis, comparison, trends, distribution, proportion, income, sales, performance, etc.
#### 2. `create_data_visualization` (Creation Tool)
- **Responsibility**: Creates visual charts based on the data provided by the user.
- **Input**: Data array + Optional title, description, chart type.
- **Output**: Complete vis-chart format code block.
- **Features**: Specifically responsible for chart generation, automatically infers field mapping.
## 🚀 Quick Start
### Using npx (Recommended)
```bash
npx -y gpt-vis-mcp
```
### Using npm
```bash
npm install -g gpt-vis-mcp
```
### Building from Source
```bash
# Clone the project
git clone https://github.com/BoyYangzai/gpt-vis-mcp.git
cd gpt-vis-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
```
## 🔧 Configuration
### Cursor MCP Configuration
Add the following configuration in Cursor's MCP settings:
```json
{
"mcpServers": {
"gpt-vis": {
"command": "npx",
"args": ["-y", "gpt-vis-mcp"]
}
}
}
```
### Claude Desktop Configuration
Add the following in `claude_desktop_config.json`:
```json
{
"mcpServers": {
"gpt-vis": {
"command": "npx",
"args": ["-y", "gpt-vis-mcp"]
}
}
}
```
### Local Development Configuration
If you want to use the locally built version:
```json
{
"mcpServers": {
"gpt-vis": {
"command": "node",
"args": ["/path/to/gpt-vis-mcp/dist/index.js"]
}
}
}
```
## 📊 Intelligent Judgment Logic
### Automatically Triggered Scenarios
- ✅ "Help me analyze the salary range for ByteDance's front-end development campus recruits" → Generate a bar chart.
- ✅ "Analyze sales trends" → Generate a line chart.
- ✅ "Show user age distribution" → Generate a histogram.
- ✅ "View performance comparison across departments" → Generate a bar chart.
- ❌ "How's the weather today?" → No chart generated.
- ❌ "Hello, what time is it?" → No chart generated.
### Chart Type Recommendations
- **Trend Analysis** → Line chart (line)
- **Data Comparison** → Bar chart (column)
- **Proportion Analysis** → Pie chart (pie)
- **Distribution Statistics** → Histogram (histogram)
## 📈 Output Format
All charts are output in standard vis-chart format:
```vis-chart
{
"type": "line",
"data": [
{
"Level": "Cabbage offer",
"Annual Salary (10,000 RMB)": 38,
"Monthly Salary (k)": 24,
"Details": "24k*15 salaries + housing allowance 1.5k*12"
},
{
"Level": "SP offer",
"Annual Salary (10,000 RMB)": 44,
"Monthly Salary (k)": 28,
"Details": "28k*15 salaries + housing allowance + signing bonus 10k"
},
{
"Level": "SSP offer",
"Annual Salary (10,000 RMB)": 50,
"Monthly Salary (k)": 32,
"Details": "30-32k*15 salaries + housing allowance + signing bonus + options"
}
],
"title": "Statistics of Salary Range for ByteDance's Front-end Development Campus Recruits"
}
```
## 🎨 Supported Chart Types
- 📊 Bar chart (column/bar)
- 📈 Line chart (line)
- 🥧 Pie chart (pie)
- 📋 Histogram (histogram)
- 🔥 Heatmap (heatmap)
- 📍 Scatter plot (scatter)
- 📊 Area chart (area)
- 🕸️ Radar chart (radar)
- 🗂️ Treemap (treemap)
- ☁️ Word cloud (word-cloud)
## 🔍 Testing and Validation
Run tests to validate tool functionality:
```bash
npm test
```
Tests include:
- ✅ Intelligent judgment of visualization needs.
- ✅ Automatic generation of corresponding charts.
- ✅ Correctly rejecting non-data-related questions.
- ✅ Forcing the creation of specified charts.
## 💡 Design Philosophy
The core value of this MCP tool lies in **an intelligent user experience**:
1. **Zero Learning Curve**: Users do not need to learn special commands.
2. **Automated Processing**: AI automatically judges and generates charts.
3. **100% Response Rate**: Ensures that all data-related questions receive visualization support.
4. **Ready to Use**: Simple configuration, powerful functionality.
## 🔗 Related Projects
- [Official AntV MCP](https://github.com/antvis/mcp-server-chart) - Static chart generation.
- [GPT-Vis](https://github.com/observablehq/gpt-vis) - Visualization chart library.
This project focuses on **intelligent recommendations and dynamic generation**, complementing the official projects.
---
**Making data visualization smarter and more natural!** 🚀
## 🔄 Workflow
**Ideal usage flow**:
1. User asks: "Help me analyze the salary range for ByteDance's front-end development campus recruits."
2. AI invokes `check_if_needs_visualization` → Returns "Visualization needed, recommend bar chart."
3. AI prepares data based on the judgment result and invokes `create_data_visualization`.
4. Generates complete chart configuration.
**Clear Responsibilities**:
- ✅ **Judgment Tool**: Only judges whether visualization is needed + recommends type, does not generate charts.
- ✅ **Creation Tool**: Receives data parameters, specifically generates charts.
## License
MIT
