ds-mcp-server 0.1.0__tar.gz

ds_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ds-mcp-server contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ds_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: ds-mcp-server
+Version: 0.1.0
+Summary: An MCP server exposing data science tools (plotting, stats, data exploration) to any LLM client.
+Author: Ahmad Alhineidi
+License: MIT
+Keywords: mcp,llm,data-science,visualization,plotly,pandas
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: plotly>=5.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: seaborn>=0.13
+Requires-Dist: numpy>=1.24
+Requires-Dist: pingouin>=0.5
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: wordcloud>=1.9
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: ddgs>=6.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: openai>=1.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.20; extra == "anthropic"
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == "playwright"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.20; extra == "all"
+Requires-Dist: playwright>=1.40; extra == "all"
+Dynamic: license-file
+
+# ds-mcp-server
+
+`ds-mcp-server` packages a FastMCP server with data science, plotting, statistics, system, and web tools, plus interactive CLI clients for OpenAI-compatible providers and Anthropic Claude.
+
+## Installation
+
+Future PyPI install:
+
+```bash
+pip install ds-mcp-server
+```
+
+Local development install:
+
+```bash
+pip install -e .
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[anthropic]"
+pip install -e ".[playwright]"
+pip install -e ".[all]"
+```
+
+## Quick start
+
+1. Copy `.env.example` to `.env`.
+2. Fill in your provider settings.
+3. Install the package.
+4. Start either the MCP server or the interactive client.
+
+### OpenAI
+
+```bash
+export PROVIDER=openai
+export API_KEY=sk-...
+export MODEL=gpt-4o
+ds-mcp-client
+```
+
+### Claude / Anthropic
+
+```bash
+export PROVIDER=anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+export MODEL=claude-opus-4-5
+ds-mcp-client
+```
+
+### Gemini (OpenAI-compatible endpoint)
+
+```bash
+export PROVIDER=gemini
+export API_KEY=AIza...
+export MODEL=gemini-2.0-flash
+ds-mcp-client
+```
+
+### Ollama
+
+```bash
+export PROVIDER=ollama
+export API_BASE_URL=http://localhost:11434/v1
+export MODEL=llama3
+ds-mcp-client
+```
+
+### GPUStack / LM Studio / other OpenAI-compatible servers
+
+```bash
+export PROVIDER=openai-compat
+export API_BASE_URL=https://your-endpoint.example/v1
+export API_KEY=your-key
+export MODEL=your-model
+ds-mcp-client
+```
+
+## Running the MCP server
+
+```bash
+ds-mcp-server
+```
+
+## Claude Desktop MCP config
+
+Add the server to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "ds-mcp-server": {
+      "command": "ds-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `PROVIDER` | No | One of `openai`, `anthropic`, `gemini`, `ollama`, `openai-compat`. |
+| `API_KEY` | Usually | Generic API key used by OpenAI-compatible providers and as a fallback for Anthropic. |
+| `ANTHROPIC_API_KEY` | Anthropic only | Preferred Anthropic key. |
+| `API_BASE_URL` | Sometimes | Required for `openai-compat`; optional override for Ollama, Gemini, or self-hosted endpoints. |
+| `MODEL` | No | Model override. Defaults are provider-specific. |
+
+## Available tools
+
+### Interactive plots
+
+- `plot_interactive_histogram`
+- `plot_interactive_scatterplot`
+- `plot_interactive_boxplot`
+- `plot_interactive_lineplot`
+- `plot_interactive_barchart`
+- `plot_interactive_scatter_matrix`
+- `plot_interactive_correlation_heatmap`
+- `generate_custom_plotly`
+- `get_all_columns_summary`
+- `get_column_summary`
+
+### Static plots
+
+- `plot_static_histogram`
+- `plot_static_scatterplot`
+- `plot_static_boxplot`
+- `plot_static_lineplot`
+- `plot_static_barchart`
+- `plot_static_pairplot`
+- `plot_static_correlation_heatmap`
+- `plot_static_wordcloud`
+- `generate_custom_static_plot`
+
+### Statistical analysis
+
+- `run_correlation`
+- `run_group_comparison`
+- `run_linear_regression`
+- `rank_target_correlations`
+
+### System tools
+
+- `run_shell_command`
+- `read_file`
+- `write_file`
+- `patch_file`
+- `list_directory`
+- `find_in_files`
+- `run_background_process`
+- `stop_background_process`
+- `list_background_processes`
+- `http_request`
+
+### Web tools
+
+- `search_web`
+- `fetch_webpage`
+- `screenshot_webpage`
+
+## Requirements
+
+- Python 3.11+
+- `mcp`
+- `pandas`, `numpy`
+- `plotly`, `matplotlib`, `seaborn`, `wordcloud`
+- `pingouin`, `statsmodels`
+- `beautifulsoup4`, `ddgs`
+- `openai`
+- `anthropic` (optional)
+- `playwright` (optional, for screenshots)

ds_mcp_server-0.1.0/README.md

@@ -0,0 +1,174 @@
+# ds-mcp-server
+
+`ds-mcp-server` packages a FastMCP server with data science, plotting, statistics, system, and web tools, plus interactive CLI clients for OpenAI-compatible providers and Anthropic Claude.
+
+## Installation
+
+Future PyPI install:
+
+```bash
+pip install ds-mcp-server
+```
+
+Local development install:
+
+```bash
+pip install -e .
+```
+
+Optional extras:
+
+```bash
+pip install -e ".[anthropic]"
+pip install -e ".[playwright]"
+pip install -e ".[all]"
+```
+
+## Quick start
+
+1. Copy `.env.example` to `.env`.
+2. Fill in your provider settings.
+3. Install the package.
+4. Start either the MCP server or the interactive client.
+
+### OpenAI
+
+```bash
+export PROVIDER=openai
+export API_KEY=sk-...
+export MODEL=gpt-4o
+ds-mcp-client
+```
+
+### Claude / Anthropic
+
+```bash
+export PROVIDER=anthropic
+export ANTHROPIC_API_KEY=sk-ant-...
+export MODEL=claude-opus-4-5
+ds-mcp-client
+```
+
+### Gemini (OpenAI-compatible endpoint)
+
+```bash
+export PROVIDER=gemini
+export API_KEY=AIza...
+export MODEL=gemini-2.0-flash
+ds-mcp-client
+```
+
+### Ollama
+
+```bash
+export PROVIDER=ollama
+export API_BASE_URL=http://localhost:11434/v1
+export MODEL=llama3
+ds-mcp-client
+```
+
+### GPUStack / LM Studio / other OpenAI-compatible servers
+
+```bash
+export PROVIDER=openai-compat
+export API_BASE_URL=https://your-endpoint.example/v1
+export API_KEY=your-key
+export MODEL=your-model
+ds-mcp-client
+```
+
+## Running the MCP server
+
+```bash
+ds-mcp-server
+```
+
+## Claude Desktop MCP config
+
+Add the server to your Claude Desktop MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "ds-mcp-server": {
+      "command": "ds-mcp-server",
+      "args": []
+    }
+  }
+}
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `PROVIDER` | No | One of `openai`, `anthropic`, `gemini`, `ollama`, `openai-compat`. |
+| `API_KEY` | Usually | Generic API key used by OpenAI-compatible providers and as a fallback for Anthropic. |
+| `ANTHROPIC_API_KEY` | Anthropic only | Preferred Anthropic key. |
+| `API_BASE_URL` | Sometimes | Required for `openai-compat`; optional override for Ollama, Gemini, or self-hosted endpoints. |
+| `MODEL` | No | Model override. Defaults are provider-specific. |
+
+## Available tools
+
+### Interactive plots
+
+- `plot_interactive_histogram`
+- `plot_interactive_scatterplot`
+- `plot_interactive_boxplot`
+- `plot_interactive_lineplot`
+- `plot_interactive_barchart`
+- `plot_interactive_scatter_matrix`
+- `plot_interactive_correlation_heatmap`
+- `generate_custom_plotly`
+- `get_all_columns_summary`
+- `get_column_summary`
+
+### Static plots
+
+- `plot_static_histogram`
+- `plot_static_scatterplot`
+- `plot_static_boxplot`
+- `plot_static_lineplot`
+- `plot_static_barchart`
+- `plot_static_pairplot`
+- `plot_static_correlation_heatmap`
+- `plot_static_wordcloud`
+- `generate_custom_static_plot`
+
+### Statistical analysis
+
+- `run_correlation`
+- `run_group_comparison`
+- `run_linear_regression`
+- `rank_target_correlations`
+
+### System tools
+
+- `run_shell_command`
+- `read_file`
+- `write_file`
+- `patch_file`
+- `list_directory`
+- `find_in_files`
+- `run_background_process`
+- `stop_background_process`
+- `list_background_processes`
+- `http_request`
+
+### Web tools
+
+- `search_web`
+- `fetch_webpage`
+- `screenshot_webpage`
+
+## Requirements
+
+- Python 3.11+
+- `mcp`
+- `pandas`, `numpy`
+- `plotly`, `matplotlib`, `seaborn`, `wordcloud`
+- `pingouin`, `statsmodels`
+- `beautifulsoup4`, `ddgs`
+- `openai`
+- `anthropic` (optional)
+- `playwright` (optional, for screenshots)

ds_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta:__legacy__"
+
+[project]
+name = "ds-mcp-server"
+version = "0.1.0"
+description = "An MCP server exposing data science tools (plotting, stats, data exploration) to any LLM client."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Ahmad Alhineidi" }]
+keywords = ["mcp", "llm", "data-science", "visualization", "plotly", "pandas"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Visualization",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pandas>=2.0",
+    "plotly>=5.0",
+    "matplotlib>=3.7",
+    "seaborn>=0.13",
+    "numpy>=1.24",
+    "pingouin>=0.5",
+    "statsmodels>=0.14",
+    "wordcloud>=1.9",
+    "beautifulsoup4>=4.12",
+    "ddgs>=6.0",
+    "python-dotenv>=1.0",
+    "openai>=1.0",
+]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.20"]
+playwright = ["playwright>=1.40"]
+all = ["anthropic>=0.20", "playwright>=1.40"]
+
+[project.scripts]
+ds-mcp-server = "ds_mcp_server.cli:serve"
+ds-mcp-client = "ds_mcp_server.cli:chat"
+
+[tool.setuptools.packages.find]
+where = ["src"]

ds_mcp_server-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ds_mcp_server-0.1.0/src/ds_mcp_server/__init__.py

@@ -0,0 +1,2 @@
+"""ds-mcp-server — Data Science MCP Server and multi-provider client."""
+__version__ = "0.1.0"

ds_mcp_server-0.1.0/src/ds_mcp_server/_tools/plot_data.py

@@ -0,0 +1,106 @@
+"""
+Data Exploration Module for the AI Visualization Engine.
+Provides tools for the LLM to inspect dataset columns before plotting.
+"""
+
+import pandas as pd
+
+from .viz_config import MAX_ROWS
+from .viz_utils import load_data_safely, was_last_load_truncated
+
+
+def get_column_summary_impl(data_file_path: str, column: str) -> str:
+    """
+    Analyzes a specific column in the dataset and returns a statistical summary.
+    
+    For numeric columns, it calculates the minimum, maximum, mean, and null count.
+    For categorical columns, it calculates the number of unique values, lists 
+    the top 10 unique values, and the null count.
+
+    Args:
+        data_file_path: The absolute path to the data file.
+        column: The name of the column to analyze.
+
+    Returns:
+        A formatted string containing the column statistics, or an error message
+        if the column cannot be found or analyzed.
+    """
+    try:
+        df = load_data_safely(data_file_path)
+
+        truncation_note = ""
+        if was_last_load_truncated(data_file_path):
+            truncation_note = (
+                f"\n\nNote: dataset was truncated to the first {MAX_ROWS:,} rows for "
+                "memory safety. Mention this in your final summary."
+            )
+
+        if column not in df.columns:
+            return f"Error: Column '{column}' not found in the dataset."
+            
+        col_data = df[column]
+        null_count = col_data.isna().sum()
+        
+        if pd.api.types.is_numeric_dtype(col_data):
+            min_val = col_data.min()
+            max_val = col_data.max()
+            mean_val = col_data.mean()
+            
+            return (
+                f"Numeric Column '{column}': Min={min_val}, Max={max_val}, "
+                f"Mean={mean_val:.2f}, Nulls={null_count}{truncation_note}"
+            )
+        else:
+            unique_vals = col_data.unique()
+            total_unique = len(unique_vals)
+            
+            if total_unique > 10:
+                top_vals = ", ".join(map(str, unique_vals[:10]))
+                val_str = f"{top_vals}... (+ {total_unique - 10} more)"
+            else:
+                val_str = ", ".join(map(str, unique_vals))
+                
+            return (
+                f"Categorical Column '{column}': {total_unique} unique values. "
+                f"Top values: {val_str}. Nulls={null_count}{truncation_note}"
+            )
+
+    except Exception as e:
+        return f"Error analyzing column '{column}': {str(e)}"
+
+
+def get_all_columns_summary_impl(data_file_path: str) -> str:
+    """
+    Returns a compact schema of every column: name and type only.
+    Intentionally terse to minimise token load on the model.
+    Use get_column_summary for detailed stats on a specific column.
+    """
+    try:
+        df = load_data_safely(data_file_path)
+
+        truncation_note = ""
+        if was_last_load_truncated(data_file_path):
+            truncation_note = f" (truncated to {MAX_ROWS:,} rows)"
+
+        numeric_cols = [c for c in df.columns if pd.api.types.is_numeric_dtype(df[c])]
+        datetime_cols = [c for c in df.columns if pd.api.types.is_datetime64_any_dtype(df[c])]
+        categorical_cols = [c for c in df.columns if c not in numeric_cols and c not in datetime_cols]
+
+        lines = [
+            f"Dataset: {len(df):,} rows × {len(df.columns)} columns{truncation_note}",
+            f"Numeric columns ({len(numeric_cols)}): {', '.join(numeric_cols)}",
+        ]
+        if categorical_cols:
+            cat_details = []
+            for c in categorical_cols:
+                unique_vals = df[c].dropna().unique()
+                sample = ", ".join(str(v) for v in sorted(unique_vals, key=str)[:5])
+                cat_details.append(f"{c} [{sample}]")
+            lines.append(f"Categorical columns ({len(categorical_cols)}): {'; '.join(cat_details)}")
+        if datetime_cols:
+            lines.append(f"Datetime columns ({len(datetime_cols)}): {', '.join(datetime_cols)}")
+
+        return "\n".join(lines)
+
+    except Exception as e:
+        return f"Error summarizing columns: {str(e)}"