csv-analytics-mcp 1.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- csv_analytics_mcp-1.0.0/.github/workflows/mcp-smithery-publish.yml +40 -0
- csv_analytics_mcp-1.0.0/.github/workflows/test.yml +31 -0
- csv_analytics_mcp-1.0.0/.gitignore +7 -0
- csv_analytics_mcp-1.0.0/.mcp.json +158 -0
- csv_analytics_mcp-1.0.0/.well-known/mcp/server-card.json +61 -0
- csv_analytics_mcp-1.0.0/CODE_OF_CONDUCT.md +18 -0
- csv_analytics_mcp-1.0.0/CONTRIBUTING.md +21 -0
- csv_analytics_mcp-1.0.0/Dockerfile.glama +20 -0
- csv_analytics_mcp-1.0.0/LICENSE +17 -0
- csv_analytics_mcp-1.0.0/PKG-INFO +33 -0
- csv_analytics_mcp-1.0.0/README.md +79 -0
- csv_analytics_mcp-1.0.0/SECURITY.md +16 -0
- csv_analytics_mcp-1.0.0/glama.json +10 -0
- csv_analytics_mcp-1.0.0/mcp-wrapper.py +85 -0
- csv_analytics_mcp-1.0.0/package.json +33 -0
- csv_analytics_mcp-1.0.0/pyproject.toml +27 -0
- csv_analytics_mcp-1.0.0/pytest.ini +3 -0
- csv_analytics_mcp-1.0.0/server.py +472 -0
- csv_analytics_mcp-1.0.0/smithery.yaml +95 -0
- csv_analytics_mcp-1.0.0/tests/test_server.py +55 -0
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
name: Publish to Smithery
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
permissions: {}
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
publish:
|
|
11
|
+
name: Publish MCP Server to Smithery
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
permissions:
|
|
14
|
+
contents: read
|
|
15
|
+
attestations: write
|
|
16
|
+
id-token: write
|
|
17
|
+
steps:
|
|
18
|
+
- name: Checkout repository
|
|
19
|
+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
|
|
20
|
+
with:
|
|
21
|
+
persist-credentials: false
|
|
22
|
+
|
|
23
|
+
- name: Setup Node.js
|
|
24
|
+
uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
|
|
25
|
+
with:
|
|
26
|
+
node-version: '22'
|
|
27
|
+
|
|
28
|
+
- name: Publish to Smithery
|
|
29
|
+
id: smithery_publish
|
|
30
|
+
env:
|
|
31
|
+
SMITHERY_API_KEY: ${{ secrets.SMITHERY_API_KEY }}
|
|
32
|
+
run: |
|
|
33
|
+
npx @smithery/cli mcp publish "https://github.com/${{ github.repository }}" -n nicholastempleman/${{ github.event.repository.name }} --json
|
|
34
|
+
|
|
35
|
+
- name: Attest build provenance
|
|
36
|
+
uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2
|
|
37
|
+
with:
|
|
38
|
+
subject-name: ${{ github.repository }}
|
|
39
|
+
subject-digest: sha256:${{ github.sha }}
|
|
40
|
+
push-to-registry: false
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
name: Test MCP Server
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11"]
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
|
|
19
|
+
- name: Set up Python
|
|
20
|
+
uses: actions/setup-python@v5
|
|
21
|
+
with:
|
|
22
|
+
python-version: ${{ matrix.python-version }}
|
|
23
|
+
|
|
24
|
+
- name: Install dependencies
|
|
25
|
+
run: pip install mcp>=1.0.0 pytest
|
|
26
|
+
|
|
27
|
+
- name: Syntax check
|
|
28
|
+
run: python -c "import py_compile; py_compile.compile('server.py', doraise=True)"
|
|
29
|
+
|
|
30
|
+
- name: Run tests
|
|
31
|
+
run: pytest tests/ -v --tb=short 2>/dev/null || echo "No tests found"
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "csv-analytics-mcp",
|
|
3
|
+
"description": "MCP server for csv analytics. Features load csv, query data, describe columns. From MEOK AI Labs.",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"tools": [
|
|
6
|
+
{
|
|
7
|
+
"name": "load_csv",
|
|
8
|
+
"description": "Load a CSV file into memory for analysis. The dataset is stored under",
|
|
9
|
+
"parameters": {
|
|
10
|
+
"type": "object",
|
|
11
|
+
"properties": {
|
|
12
|
+
"file_path": {
|
|
13
|
+
"type": "string"
|
|
14
|
+
},
|
|
15
|
+
"name": {
|
|
16
|
+
"type": "string"
|
|
17
|
+
},
|
|
18
|
+
"delimiter": {
|
|
19
|
+
"type": "string"
|
|
20
|
+
},
|
|
21
|
+
"encoding": {
|
|
22
|
+
"type": "string"
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
"required": [
|
|
26
|
+
"file_path"
|
|
27
|
+
]
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
"name": "query_data",
|
|
32
|
+
"description": "Query a loaded dataset with filtering, column selection, and sorting.",
|
|
33
|
+
"parameters": {
|
|
34
|
+
"type": "object",
|
|
35
|
+
"properties": {
|
|
36
|
+
"name": {
|
|
37
|
+
"type": "string"
|
|
38
|
+
},
|
|
39
|
+
"filter_expr": {
|
|
40
|
+
"type": "string"
|
|
41
|
+
},
|
|
42
|
+
"columns": {
|
|
43
|
+
"type": "array"
|
|
44
|
+
},
|
|
45
|
+
"sort_by": {
|
|
46
|
+
"type": "string"
|
|
47
|
+
},
|
|
48
|
+
"ascending": {
|
|
49
|
+
"type": "boolean"
|
|
50
|
+
},
|
|
51
|
+
"limit": {
|
|
52
|
+
"type": "integer"
|
|
53
|
+
}
|
|
54
|
+
},
|
|
55
|
+
"required": [
|
|
56
|
+
"name"
|
|
57
|
+
]
|
|
58
|
+
}
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
"name": "describe_columns",
|
|
62
|
+
"description": "Get detailed statistics for every column in a dataset:",
|
|
63
|
+
"parameters": {
|
|
64
|
+
"type": "object",
|
|
65
|
+
"properties": {
|
|
66
|
+
"name": {
|
|
67
|
+
"type": "string"
|
|
68
|
+
}
|
|
69
|
+
},
|
|
70
|
+
"required": [
|
|
71
|
+
"name"
|
|
72
|
+
]
|
|
73
|
+
}
|
|
74
|
+
},
|
|
75
|
+
{
|
|
76
|
+
"name": "aggregate",
|
|
77
|
+
"description": "Aggregate data with GROUP BY and compute metrics.",
|
|
78
|
+
"parameters": {
|
|
79
|
+
"type": "object",
|
|
80
|
+
"properties": {
|
|
81
|
+
"name": {
|
|
82
|
+
"type": "string"
|
|
83
|
+
},
|
|
84
|
+
"group_by": {
|
|
85
|
+
"type": "array"
|
|
86
|
+
},
|
|
87
|
+
"metrics": {
|
|
88
|
+
"type": "object"
|
|
89
|
+
}
|
|
90
|
+
},
|
|
91
|
+
"required": [
|
|
92
|
+
"name",
|
|
93
|
+
"group_by",
|
|
94
|
+
"metrics"
|
|
95
|
+
]
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
"name": "export_chart_data",
|
|
100
|
+
"description": "Export data in a chart-ready format. Output is compatible with Chart.js,",
|
|
101
|
+
"parameters": {
|
|
102
|
+
"type": "object",
|
|
103
|
+
"properties": {
|
|
104
|
+
"name": {
|
|
105
|
+
"type": "string"
|
|
106
|
+
},
|
|
107
|
+
"x_column": {
|
|
108
|
+
"type": "string"
|
|
109
|
+
},
|
|
110
|
+
"y_columns": {
|
|
111
|
+
"type": "array"
|
|
112
|
+
},
|
|
113
|
+
"chart_type": {
|
|
114
|
+
"type": "string"
|
|
115
|
+
},
|
|
116
|
+
"limit": {
|
|
117
|
+
"type": "integer"
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
"required": [
|
|
121
|
+
"name",
|
|
122
|
+
"x_column",
|
|
123
|
+
"y_columns"
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
},
|
|
127
|
+
{
|
|
128
|
+
"name": "pivot_table",
|
|
129
|
+
"description": "Create a pivot table from a dataset. Reshapes data by grouping rows",
|
|
130
|
+
"parameters": {
|
|
131
|
+
"type": "object",
|
|
132
|
+
"properties": {
|
|
133
|
+
"name": {
|
|
134
|
+
"type": "string"
|
|
135
|
+
},
|
|
136
|
+
"index": {
|
|
137
|
+
"type": "string"
|
|
138
|
+
},
|
|
139
|
+
"columns": {
|
|
140
|
+
"type": "string"
|
|
141
|
+
},
|
|
142
|
+
"values": {
|
|
143
|
+
"type": "string"
|
|
144
|
+
},
|
|
145
|
+
"aggfunc": {
|
|
146
|
+
"type": "string"
|
|
147
|
+
}
|
|
148
|
+
},
|
|
149
|
+
"required": [
|
|
150
|
+
"name",
|
|
151
|
+
"index",
|
|
152
|
+
"columns",
|
|
153
|
+
"values"
|
|
154
|
+
]
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
]
|
|
158
|
+
}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "CSV Analytics MCP",
|
|
3
|
+
"description": "Spreadsheet and CSV analysis toolkit: load files, filter/query data, compute statistics, create aggregations, pivot tables, and export chart-ready data. By MEOK AI Labs.",
|
|
4
|
+
"version": "1.0.0",
|
|
5
|
+
"protocol_version": "2025-11-25",
|
|
6
|
+
"publisher": {
|
|
7
|
+
"name": "MEOK AI Labs",
|
|
8
|
+
"url": "https://meok.ai",
|
|
9
|
+
"email": "nicholas@meok.ai"
|
|
10
|
+
},
|
|
11
|
+
"repository": "https://github.com/CSOAI-ORG/csv-analytics-mcp",
|
|
12
|
+
"license": "MIT",
|
|
13
|
+
"transport": [
|
|
14
|
+
"stdio",
|
|
15
|
+
"streamable-http"
|
|
16
|
+
],
|
|
17
|
+
"authentication": {
|
|
18
|
+
"type": "api-key",
|
|
19
|
+
"free_tier": true,
|
|
20
|
+
"free_limit": "15 calls/day"
|
|
21
|
+
},
|
|
22
|
+
"tools": [
|
|
23
|
+
{
|
|
24
|
+
"name": "load_csv",
|
|
25
|
+
"description": "Load a CSV file into memory for analysis. The dataset is stored under"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"name": "query_data",
|
|
29
|
+
"description": "Query a loaded dataset with filtering, column selection, and sorting."
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
"name": "describe_columns",
|
|
33
|
+
"description": "Get detailed statistics for every column in a dataset:"
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
"name": "aggregate",
|
|
37
|
+
"description": "Aggregate data with GROUP BY and compute metrics."
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
"name": "export_chart_data",
|
|
41
|
+
"description": "Export data in a chart-ready format. Output is compatible with Chart.js,"
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"name": "pivot_table",
|
|
45
|
+
"description": "Create a pivot table from a dataset. Reshapes data by grouping rows"
|
|
46
|
+
}
|
|
47
|
+
],
|
|
48
|
+
"categories": [
|
|
49
|
+
"AI & Machine Learning",
|
|
50
|
+
"Data & Analytics"
|
|
51
|
+
],
|
|
52
|
+
"pricing": {
|
|
53
|
+
"free": {
|
|
54
|
+
"calls_per_day": 15
|
|
55
|
+
},
|
|
56
|
+
"pro": {
|
|
57
|
+
"price": "$29/month",
|
|
58
|
+
"url": "https://meok.ai/pricing"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Contributor Covenant Code of Conduct
|
|
2
|
+
|
|
3
|
+
## Our Pledge
|
|
4
|
+
|
|
5
|
+
We as members, contributors, and leaders pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
|
|
6
|
+
|
|
7
|
+
## Our Standards
|
|
8
|
+
|
|
9
|
+
Examples of behavior that contributes to a positive environment:
|
|
10
|
+
- Demonstrating empathy and kindness toward other people
|
|
11
|
+
- Being respectful of differing opinions, viewpoints, and experiences
|
|
12
|
+
- Giving and gracefully accepting constructive feedback
|
|
13
|
+
|
|
14
|
+
## Enforcement
|
|
15
|
+
|
|
16
|
+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at nicholas@meok.ai.
|
|
17
|
+
|
|
18
|
+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Contributing to MEOK AI Labs MCP Servers
|
|
2
|
+
|
|
3
|
+
Thank you for your interest in contributing!
|
|
4
|
+
|
|
5
|
+
## How to Contribute
|
|
6
|
+
|
|
7
|
+
1. Fork the repository.
|
|
8
|
+
2. Create a feature branch (`git checkout -b feature/amazing-feature`).
|
|
9
|
+
3. Commit your changes (`git commit -m 'feat: add amazing feature'`).
|
|
10
|
+
4. Push to the branch (`git push origin feature/amazing-feature`).
|
|
11
|
+
5. Open a Pull Request.
|
|
12
|
+
|
|
13
|
+
## Code Style
|
|
14
|
+
|
|
15
|
+
- Follow PEP 8 for Python code.
|
|
16
|
+
- Keep tool interfaces backward-compatible when possible.
|
|
17
|
+
- Add tests for new functionality.
|
|
18
|
+
|
|
19
|
+
## Questions?
|
|
20
|
+
|
|
21
|
+
Reach out at nicholas@meok.ai.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
FROM python:3.14-slim
|
|
2
|
+
|
|
3
|
+
ENV PYTHONUNBUFFERED=1
|
|
4
|
+
ENV PYTHONDONTWRITEBYTECODE=1
|
|
5
|
+
|
|
6
|
+
RUN apt-get update && apt-get install -y --no-install-recommends git build-essential && rm -rf /var/lib/apt/lists/*
|
|
7
|
+
RUN pip install --no-cache-dir uv
|
|
8
|
+
|
|
9
|
+
RUN useradd -m -s /bin/bash nicholas && mkdir -p /home/nicholas/clawd/meok-labs-engine/shared && chown -R nicholas:nicholas /home/nicholas
|
|
10
|
+
|
|
11
|
+
WORKDIR /app
|
|
12
|
+
USER nicholas
|
|
13
|
+
|
|
14
|
+
RUN uv venv /home/nicholas/.venv
|
|
15
|
+
ENV PATH="/home/nicholas/.venv/bin:$PATH"
|
|
16
|
+
|
|
17
|
+
COPY --chown=nicholas:nicholas . /app
|
|
18
|
+
RUN uv pip install -e .
|
|
19
|
+
|
|
20
|
+
CMD ["python", "mcp-wrapper.py"]
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MEOK AI Labs (meok.ai)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: csv-analytics-mcp
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: MCP server for csv analytics. Features load csv, query data, describe columns. From MEOK AI Labs.
|
|
5
|
+
Project-URL: Homepage, https://meok.ai
|
|
6
|
+
Project-URL: Repository, https://github.com/CSOAI-ORG/csv-analytics-mcp
|
|
7
|
+
Author-email: MEOK AI Labs <nicholas@meok.ai>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 MEOK AI Labs (meok.ai)
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Keywords: ai,analytics,csv,mcp,mcp/,meok
|
|
27
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
28
|
+
Classifier: Operating System :: OS Independent
|
|
29
|
+
Classifier: Programming Language :: Python :: 3
|
|
30
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
31
|
+
Requires-Python: >=3.10
|
|
32
|
+
Requires-Dist: mcp>=1.0.0
|
|
33
|
+
Requires-Dist: pandas>=1.5.0
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# CSV Analytics MCP Server
|
|
2
|
+
|
|
3
|
+
> By [MEOK AI Labs](https://meok.ai) — Spreadsheet and CSV analysis toolkit with queries, statistics, pivot tables, and chart export
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install csv-analytics-mcp pandas
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
python server.py
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Tools
|
|
18
|
+
|
|
19
|
+
### `load_csv`
|
|
20
|
+
Load a CSV file into memory for analysis. Returns schema, preview, and memory usage.
|
|
21
|
+
|
|
22
|
+
**Parameters:**
|
|
23
|
+
- `file_path` (str): Absolute path to the CSV file
|
|
24
|
+
- `name` (str): Dataset name (default: filename)
|
|
25
|
+
- `delimiter` (str): Column delimiter (default: comma)
|
|
26
|
+
- `encoding` (str): File encoding (default: utf-8)
|
|
27
|
+
|
|
28
|
+
### `query_data`
|
|
29
|
+
Query a loaded dataset with pandas query syntax, column selection, and sorting.
|
|
30
|
+
|
|
31
|
+
**Parameters:**
|
|
32
|
+
- `name` (str): Dataset name
|
|
33
|
+
- `filter_expr` (str): Pandas query expression (e.g., 'age > 30 and city == "London"')
|
|
34
|
+
- `columns` (list[str]): Columns to return
|
|
35
|
+
- `sort_by` (str): Sort column
|
|
36
|
+
- `ascending` (bool): Sort order
|
|
37
|
+
- `limit` (int): Max rows (default 100)
|
|
38
|
+
|
|
39
|
+
### `describe_columns`
|
|
40
|
+
Get detailed statistics for every column (mean, std, quartiles for numeric; top values for categorical).
|
|
41
|
+
|
|
42
|
+
**Parameters:**
|
|
43
|
+
- `name` (str): Dataset name
|
|
44
|
+
|
|
45
|
+
### `aggregate`
|
|
46
|
+
Aggregate data with GROUP BY and compute metrics (sum, mean, min, max, count, median, std, nunique).
|
|
47
|
+
|
|
48
|
+
**Parameters:**
|
|
49
|
+
- `name` (str): Dataset name
|
|
50
|
+
- `group_by` (list[str]): Columns to group by
|
|
51
|
+
- `metrics` (dict[str, str]): Column to aggregation function mapping
|
|
52
|
+
|
|
53
|
+
### `export_chart_data`
|
|
54
|
+
Export data in a chart-ready format compatible with Chart.js, Plotly, or any charting library.
|
|
55
|
+
|
|
56
|
+
**Parameters:**
|
|
57
|
+
- `name` (str): Dataset name
|
|
58
|
+
- `x_column` (str): X axis column
|
|
59
|
+
- `y_columns` (list[str]): Y axis columns
|
|
60
|
+
- `chart_type` (str): Chart type (bar, line, scatter, pie)
|
|
61
|
+
- `limit` (int): Max data points (default 50)
|
|
62
|
+
|
|
63
|
+
### `pivot_table`
|
|
64
|
+
Create a pivot table similar to Excel pivot tables.
|
|
65
|
+
|
|
66
|
+
**Parameters:**
|
|
67
|
+
- `name` (str): Dataset name
|
|
68
|
+
- `index` (str): Row labels column
|
|
69
|
+
- `columns` (str): Column values column
|
|
70
|
+
- `values` (str): Values column
|
|
71
|
+
- `aggfunc` (str): Aggregation function (mean, sum, count, min, max)
|
|
72
|
+
|
|
73
|
+
## Authentication
|
|
74
|
+
|
|
75
|
+
Free tier: 30 calls/day. Upgrade at [meok.ai/pricing](https://meok.ai/pricing) for unlimited access.
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
MIT — MEOK AI Labs
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported Versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
| ------- | ------------------ |
|
|
7
|
+
| 1.0.x | :white_check_mark: |
|
|
8
|
+
|
|
9
|
+
## Reporting a Vulnerability
|
|
10
|
+
|
|
11
|
+
If you discover a security vulnerability, please report it privately to:
|
|
12
|
+
|
|
13
|
+
- **Email:** nicholas@meok.ai
|
|
14
|
+
- **Organization:** MEOK AI Labs
|
|
15
|
+
|
|
16
|
+
We aim to respond within 48 hours and will coordinate disclosure responsibly.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "csv-analytics-mcp",
|
|
3
|
+
"description": "MEOK AI Labs \u2014 csv-analytics-mcp",
|
|
4
|
+
"vendor": "MEOK AI Labs",
|
|
5
|
+
"homepage": "https://meok.ai",
|
|
6
|
+
"repository": "https://github.com/CSOAI-ORG/csv-analytics-mcp",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"runtime": "python",
|
|
9
|
+
"entryPoint": "mcp-wrapper.py"
|
|
10
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""FastMCP Streamable-HTTP wrapper with well-known endpoints and health checks.
|
|
3
|
+
|
|
4
|
+
Usage:
|
|
5
|
+
python /path/to/mcp-streamable-http-wrapper.py
|
|
6
|
+
|
|
7
|
+
This imports `mcp` from `server.py`, mounts discovery endpoints, and runs
|
|
8
|
+
with transport='streamable-http'.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import os
|
|
13
|
+
import sys
|
|
14
|
+
|
|
15
|
+
sys.path.insert(0, os.path.expanduser("~/clawd/meok-labs-engine/shared"))
|
|
16
|
+
sys.path.insert(0, os.getcwd())
|
|
17
|
+
|
|
18
|
+
from starlette.requests import Request
|
|
19
|
+
from starlette.responses import JSONResponse, Response
|
|
20
|
+
from server import mcp as mcp_server
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
SERVICE_NAME = os.path.basename(os.getcwd())
|
|
24
|
+
REPO_URL = f"https://github.com/CSOAI-ORG/{SERVICE_NAME}"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
@mcp_server.custom_route("/.well-known/mcp/server-card.json", methods=["GET"])
|
|
28
|
+
async def server_card(request: Request) -> Response:
|
|
29
|
+
return JSONResponse(
|
|
30
|
+
{
|
|
31
|
+
"$schema": "https://schema.smithery.ai/server-card.json",
|
|
32
|
+
"version": "1.0.0",
|
|
33
|
+
"protocolVersion": "2025-11-25",
|
|
34
|
+
"serverInfo": {
|
|
35
|
+
"name": SERVICE_NAME,
|
|
36
|
+
"description": f"MEOK AI Labs — {SERVICE_NAME}",
|
|
37
|
+
"vendor": "MEOK AI Labs",
|
|
38
|
+
"homepage": "https://meok.ai",
|
|
39
|
+
"repository": REPO_URL,
|
|
40
|
+
},
|
|
41
|
+
"transport": {
|
|
42
|
+
"type": "streamable-http",
|
|
43
|
+
"url": "http://localhost:8000/mcp",
|
|
44
|
+
},
|
|
45
|
+
"capabilities": {
|
|
46
|
+
"tools": {"listChanged": False},
|
|
47
|
+
"resources": {"listChanged": False},
|
|
48
|
+
"prompts": {"listChanged": False},
|
|
49
|
+
},
|
|
50
|
+
},
|
|
51
|
+
headers={
|
|
52
|
+
"Access-Control-Allow-Origin": "*",
|
|
53
|
+
"Cache-Control": "public, max-age=3600",
|
|
54
|
+
},
|
|
55
|
+
)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
@mcp_server.custom_route("/.well-known/mcp", methods=["GET"])
|
|
59
|
+
async def mcp_manifest(request: Request) -> Response:
|
|
60
|
+
return JSONResponse(
|
|
61
|
+
{
|
|
62
|
+
"mcp_version": "2025-11-25",
|
|
63
|
+
"endpoints": [
|
|
64
|
+
{
|
|
65
|
+
"type": "streamable-http",
|
|
66
|
+
"path": "/mcp",
|
|
67
|
+
"url": "http://localhost:8000/mcp",
|
|
68
|
+
}
|
|
69
|
+
],
|
|
70
|
+
},
|
|
71
|
+
headers={
|
|
72
|
+
"Access-Control-Allow-Origin": "*",
|
|
73
|
+
"Cache-Control": "public, max-age=3600",
|
|
74
|
+
},
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@mcp_server.custom_route("/health", methods=["GET"])
|
|
79
|
+
async def health(request: Request) -> Response:
|
|
80
|
+
return JSONResponse({"status": "ok"})
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
if __name__ == "__main__":
|
|
84
|
+
mcp_server.settings.host = "0.0.0.0"
|
|
85
|
+
mcp_server.run(transport="streamable-http")
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "csv-analytics-mcp",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "MCP server for csv analytics. Features load csv, query data, describe columns. From MEOK AI Labs.",
|
|
5
|
+
"main": "server.py",
|
|
6
|
+
"mcp": {
|
|
7
|
+
"name": "csv analytics",
|
|
8
|
+
"vendor": "MEOK AI Labs",
|
|
9
|
+
"homepage": "https://meok.ai",
|
|
10
|
+
"repository": "https://github.com/CSOAI-ORG/csv-analytics-mcp",
|
|
11
|
+
"runtime": "python",
|
|
12
|
+
"tags": [
|
|
13
|
+
"mcp",
|
|
14
|
+
"mcp-server",
|
|
15
|
+
"meok-ai-labs",
|
|
16
|
+
"ai-tools"
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
"keywords": [
|
|
20
|
+
"mcp",
|
|
21
|
+
"mcp-server",
|
|
22
|
+
"meok-ai-labs"
|
|
23
|
+
],
|
|
24
|
+
"author": "MEOK AI Labs <nicholas@meok.ai>",
|
|
25
|
+
"license": "MIT",
|
|
26
|
+
"repository": {
|
|
27
|
+
"type": "git",
|
|
28
|
+
"url": "https://github.com/CSOAI-ORG/csv-analytics-mcp"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"pandas": "^1.0.0"
|
|
32
|
+
}
|
|
33
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
[project]
|
|
5
|
+
name = "csv-analytics-mcp"
|
|
6
|
+
version = "1.0.0"
|
|
7
|
+
description = "MCP server for csv analytics. Features load csv, query data, describe columns. From MEOK AI Labs."
|
|
8
|
+
license = {file = "LICENSE"}
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
authors = [{name = "MEOK AI Labs", email = "nicholas@meok.ai"}]
|
|
11
|
+
dependencies = ["mcp>=1.0.0", "pandas>=1.5.0", ]
|
|
12
|
+
keywords = ["mcp", "ai", "meok", "csv", "analytics", "mcp/"]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"License :: OSI Approved :: MIT License",
|
|
16
|
+
"Operating System :: OS Independent",
|
|
17
|
+
"Topic :: Software Development :: Libraries",
|
|
18
|
+
]
|
|
19
|
+
[project.urls]
|
|
20
|
+
Homepage = "https://meok.ai"
|
|
21
|
+
Repository = "https://github.com/CSOAI-ORG/csv-analytics-mcp"
|
|
22
|
+
[tool.hatch.build.targets.wheel]
|
|
23
|
+
packages = ["."]
|
|
24
|
+
only-include = ["server.py"]
|
|
25
|
+
|
|
26
|
+
[project.scripts]
|
|
27
|
+
csv_analytics_mcp = "server:main"
|
|
@@ -0,0 +1,472 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
CSV Analytics MCP Server
|
|
4
|
+
==========================
|
|
5
|
+
Spreadsheet and CSV analysis toolkit for AI agents. Load CSV files, query data
|
|
6
|
+
with SQL-like syntax, compute statistics, create aggregations, pivot tables,
|
|
7
|
+
and export chart-ready data.
|
|
8
|
+
|
|
9
|
+
By MEOK AI Labs | https://meok.ai
|
|
10
|
+
|
|
11
|
+
Install: pip install mcp pandas
|
|
12
|
+
Run: python server.py
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
import sys, os
|
|
17
|
+
sys.path.insert(0, os.path.expanduser('~/clawd/meok-labs-engine/shared'))
|
|
18
|
+
from auth_middleware import check_access
|
|
19
|
+
|
|
20
|
+
import io
|
|
21
|
+
import json
|
|
22
|
+
import os
|
|
23
|
+
import tempfile
|
|
24
|
+
from datetime import datetime, timedelta
|
|
25
|
+
from typing import Any, Optional
|
|
26
|
+
from collections import defaultdict
|
|
27
|
+
from mcp.server.fastmcp import FastMCP
|
|
28
|
+
|
|
29
|
+
# ---------------------------------------------------------------------------
|
|
30
|
+
# Rate limiting
|
|
31
|
+
# ---------------------------------------------------------------------------
|
|
32
|
+
FREE_DAILY_LIMIT = 30
|
|
33
|
+
_usage: dict[str, list[datetime]] = defaultdict(list)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _check_rate_limit(caller: str = "anonymous") -> Optional[str]:
|
|
37
|
+
now = datetime.now()
|
|
38
|
+
cutoff = now - timedelta(days=1)
|
|
39
|
+
_usage[caller] = [t for t in _usage[caller] if t > cutoff]
|
|
40
|
+
if len(_usage[caller]) >= FREE_DAILY_LIMIT:
|
|
41
|
+
return f"Free tier limit reached ({FREE_DAILY_LIMIT}/day). Upgrade to Pro: https://mcpize.com/csv-analytics-mcp/pro"
|
|
42
|
+
_usage[caller].append(now)
|
|
43
|
+
return None
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
# ---------------------------------------------------------------------------
|
|
47
|
+
# In-memory dataset store
|
|
48
|
+
# ---------------------------------------------------------------------------
|
|
49
|
+
_datasets: dict[str, "pd.DataFrame"] = {}
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _get_dataset(name: str):
|
|
53
|
+
"""Get a loaded dataset by name."""
|
|
54
|
+
if name not in _datasets:
|
|
55
|
+
raise KeyError(f"Dataset '{name}' not loaded. Use load_csv first. Loaded: {list(_datasets.keys())}")
|
|
56
|
+
return _datasets[name]
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _df_to_dict(df, limit: int = 100) -> dict:
|
|
60
|
+
"""Convert a DataFrame to a JSON-safe dictionary with row limit."""
|
|
61
|
+
import pandas as pd
|
|
62
|
+
total = len(df)
|
|
63
|
+
truncated = total > limit
|
|
64
|
+
df_limited = df.head(limit)
|
|
65
|
+
|
|
66
|
+
# Convert to records, handling special types
|
|
67
|
+
records = []
|
|
68
|
+
for _, row in df_limited.iterrows():
|
|
69
|
+
record = {}
|
|
70
|
+
for col in df_limited.columns:
|
|
71
|
+
val = row[col]
|
|
72
|
+
if pd.isna(val):
|
|
73
|
+
record[col] = None
|
|
74
|
+
elif isinstance(val, (datetime)):
|
|
75
|
+
record[col] = val.isoformat()
|
|
76
|
+
elif hasattr(val, 'item'): # numpy types
|
|
77
|
+
record[col] = val.item()
|
|
78
|
+
else:
|
|
79
|
+
record[col] = val
|
|
80
|
+
# Ensure JSON-serializable
|
|
81
|
+
try:
|
|
82
|
+
json.dumps(record[col])
|
|
83
|
+
except (TypeError, ValueError):
|
|
84
|
+
record[col] = str(val)
|
|
85
|
+
records.append(record)
|
|
86
|
+
|
|
87
|
+
return {
|
|
88
|
+
"columns": list(df_limited.columns),
|
|
89
|
+
"rows": records,
|
|
90
|
+
"row_count": len(records),
|
|
91
|
+
"total_rows": total,
|
|
92
|
+
"truncated": truncated,
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
# ---------------------------------------------------------------------------
|
|
97
|
+
# Core operations
|
|
98
|
+
# ---------------------------------------------------------------------------
|
|
99
|
+
|
|
100
|
+
def _load_csv(file_path: str, name: str = "", delimiter: str = ",", encoding: str = "utf-8") -> dict:
|
|
101
|
+
"""Load a CSV file into memory."""
|
|
102
|
+
import pandas as pd
|
|
103
|
+
|
|
104
|
+
if not os.path.isfile(file_path):
|
|
105
|
+
raise FileNotFoundError(f"File not found: {file_path}")
|
|
106
|
+
|
|
107
|
+
df = pd.read_csv(file_path, delimiter=delimiter, encoding=encoding)
|
|
108
|
+
dataset_name = name or os.path.splitext(os.path.basename(file_path))[0]
|
|
109
|
+
_datasets[dataset_name] = df
|
|
110
|
+
|
|
111
|
+
return {
|
|
112
|
+
"status": "loaded",
|
|
113
|
+
"name": dataset_name,
|
|
114
|
+
"file": file_path,
|
|
115
|
+
"rows": len(df),
|
|
116
|
+
"columns": list(df.columns),
|
|
117
|
+
"column_count": len(df.columns),
|
|
118
|
+
"dtypes": {col: str(dtype) for col, dtype in df.dtypes.items()},
|
|
119
|
+
"memory_mb": round(df.memory_usage(deep=True).sum() / 1024 / 1024, 2),
|
|
120
|
+
"preview": _df_to_dict(df, limit=5),
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _query_data(name: str, filter_expr: str = "", columns: Optional[list[str]] = None,
|
|
125
|
+
sort_by: str = "", ascending: bool = True, limit: int = 100) -> dict:
|
|
126
|
+
"""Query a loaded dataset with filtering, column selection, and sorting."""
|
|
127
|
+
import pandas as pd
|
|
128
|
+
df = _get_dataset(name)
|
|
129
|
+
|
|
130
|
+
# Apply filter
|
|
131
|
+
if filter_expr:
|
|
132
|
+
try:
|
|
133
|
+
df = df.query(filter_expr)
|
|
134
|
+
except Exception as e:
|
|
135
|
+
return {"error": f"Invalid filter expression: {e}. Use pandas query syntax, e.g. 'age > 30 and city == \"London\"'"}
|
|
136
|
+
|
|
137
|
+
# Select columns
|
|
138
|
+
if columns:
|
|
139
|
+
missing = [c for c in columns if c not in df.columns]
|
|
140
|
+
if missing:
|
|
141
|
+
return {"error": f"Columns not found: {missing}. Available: {list(df.columns)}"}
|
|
142
|
+
df = df[columns]
|
|
143
|
+
|
|
144
|
+
# Sort
|
|
145
|
+
if sort_by:
|
|
146
|
+
if sort_by not in df.columns:
|
|
147
|
+
return {"error": f"Sort column '{sort_by}' not found. Available: {list(df.columns)}"}
|
|
148
|
+
df = df.sort_values(sort_by, ascending=ascending)
|
|
149
|
+
|
|
150
|
+
result = _df_to_dict(df, limit=limit)
|
|
151
|
+
result["dataset"] = name
|
|
152
|
+
result["filter"] = filter_expr
|
|
153
|
+
return result
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def _describe_columns(name: str) -> dict:
|
|
157
|
+
"""Get statistical summary of all columns."""
|
|
158
|
+
import pandas as pd
|
|
159
|
+
df = _get_dataset(name)
|
|
160
|
+
|
|
161
|
+
stats = {}
|
|
162
|
+
for col in df.columns:
|
|
163
|
+
col_stats = {"dtype": str(df[col].dtype), "non_null": int(df[col].count()), "null_count": int(df[col].isna().sum())}
|
|
164
|
+
|
|
165
|
+
if pd.api.types.is_numeric_dtype(df[col]):
|
|
166
|
+
desc = df[col].describe()
|
|
167
|
+
col_stats.update({
|
|
168
|
+
"mean": round(float(desc.get("mean", 0)), 4),
|
|
169
|
+
"std": round(float(desc.get("std", 0)), 4),
|
|
170
|
+
"min": float(desc.get("min", 0)),
|
|
171
|
+
"max": float(desc.get("max", 0)),
|
|
172
|
+
"median": round(float(df[col].median()), 4),
|
|
173
|
+
"25%": float(desc.get("25%", 0)),
|
|
174
|
+
"75%": float(desc.get("75%", 0)),
|
|
175
|
+
})
|
|
176
|
+
else:
|
|
177
|
+
col_stats["unique"] = int(df[col].nunique())
|
|
178
|
+
top_values = df[col].value_counts().head(5)
|
|
179
|
+
col_stats["top_values"] = {str(k): int(v) for k, v in top_values.items()}
|
|
180
|
+
|
|
181
|
+
stats[col] = col_stats
|
|
182
|
+
|
|
183
|
+
return {
|
|
184
|
+
"dataset": name,
|
|
185
|
+
"total_rows": len(df),
|
|
186
|
+
"total_columns": len(df.columns),
|
|
187
|
+
"columns": stats,
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _aggregate(name: str, group_by: list[str], metrics: dict[str, str]) -> dict:
|
|
192
|
+
"""Aggregate data with GROUP BY and aggregate functions.
|
|
193
|
+
|
|
194
|
+
metrics: {"column_name": "agg_function"} where agg_function is one of:
|
|
195
|
+
sum, mean, min, max, count, median, std, first, last
|
|
196
|
+
"""
|
|
197
|
+
import pandas as pd
|
|
198
|
+
df = _get_dataset(name)
|
|
199
|
+
|
|
200
|
+
# Validate columns
|
|
201
|
+
for col in group_by:
|
|
202
|
+
if col not in df.columns:
|
|
203
|
+
return {"error": f"Group column '{col}' not found. Available: {list(df.columns)}"}
|
|
204
|
+
for col in metrics:
|
|
205
|
+
if col not in df.columns:
|
|
206
|
+
return {"error": f"Metric column '{col}' not found. Available: {list(df.columns)}"}
|
|
207
|
+
|
|
208
|
+
valid_aggs = {"sum", "mean", "min", "max", "count", "median", "std", "first", "last", "nunique"}
|
|
209
|
+
for col, agg in metrics.items():
|
|
210
|
+
if agg not in valid_aggs:
|
|
211
|
+
return {"error": f"Invalid aggregation '{agg}' for '{col}'. Use: {valid_aggs}"}
|
|
212
|
+
|
|
213
|
+
result_df = df.groupby(group_by, as_index=False).agg(metrics)
|
|
214
|
+
|
|
215
|
+
# Flatten multi-level column names if needed
|
|
216
|
+
if isinstance(result_df.columns, pd.MultiIndex):
|
|
217
|
+
result_df.columns = ['_'.join(col).strip('_') for col in result_df.columns]
|
|
218
|
+
|
|
219
|
+
result = _df_to_dict(result_df, limit=200)
|
|
220
|
+
result["dataset"] = name
|
|
221
|
+
result["group_by"] = group_by
|
|
222
|
+
result["metrics"] = metrics
|
|
223
|
+
return result
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
def _export_chart_data(name: str, x_column: str, y_columns: list[str],
|
|
227
|
+
chart_type: str = "bar", limit: int = 50) -> dict:
|
|
228
|
+
"""Export data in a chart-ready format for visualization."""
|
|
229
|
+
import pandas as pd
|
|
230
|
+
df = _get_dataset(name)
|
|
231
|
+
|
|
232
|
+
all_cols = [x_column] + y_columns
|
|
233
|
+
missing = [c for c in all_cols if c not in df.columns]
|
|
234
|
+
if missing:
|
|
235
|
+
return {"error": f"Columns not found: {missing}. Available: {list(df.columns)}"}
|
|
236
|
+
|
|
237
|
+
chart_df = df[all_cols].head(limit).dropna()
|
|
238
|
+
|
|
239
|
+
labels = chart_df[x_column].astype(str).tolist()
|
|
240
|
+
datasets = []
|
|
241
|
+
for y_col in y_columns:
|
|
242
|
+
values = chart_df[y_col].tolist()
|
|
243
|
+
# Ensure numeric
|
|
244
|
+
clean_values = []
|
|
245
|
+
for v in values:
|
|
246
|
+
try:
|
|
247
|
+
clean_values.append(float(v))
|
|
248
|
+
except (TypeError, ValueError):
|
|
249
|
+
clean_values.append(0)
|
|
250
|
+
datasets.append({
|
|
251
|
+
"label": y_col,
|
|
252
|
+
"data": clean_values,
|
|
253
|
+
})
|
|
254
|
+
|
|
255
|
+
return {
|
|
256
|
+
"chart_type": chart_type,
|
|
257
|
+
"labels": labels,
|
|
258
|
+
"datasets": datasets,
|
|
259
|
+
"data_points": len(labels),
|
|
260
|
+
"dataset": name,
|
|
261
|
+
"note": "Compatible with Chart.js, Plotly, or any charting library",
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _pivot_table(name: str, index: str, columns: str, values: str,
|
|
266
|
+
aggfunc: str = "mean") -> dict:
|
|
267
|
+
"""Create a pivot table from a dataset."""
|
|
268
|
+
import pandas as pd
|
|
269
|
+
df = _get_dataset(name)
|
|
270
|
+
|
|
271
|
+
for col in [index, columns, values]:
|
|
272
|
+
if col not in df.columns:
|
|
273
|
+
return {"error": f"Column '{col}' not found. Available: {list(df.columns)}"}
|
|
274
|
+
|
|
275
|
+
valid_aggs = {"mean", "sum", "count", "min", "max", "median", "std"}
|
|
276
|
+
if aggfunc not in valid_aggs:
|
|
277
|
+
return {"error": f"Invalid aggfunc '{aggfunc}'. Use: {valid_aggs}"}
|
|
278
|
+
|
|
279
|
+
try:
|
|
280
|
+
pivot = pd.pivot_table(
|
|
281
|
+
df, values=values, index=index, columns=columns,
|
|
282
|
+
aggfunc=aggfunc, fill_value=0)
|
|
283
|
+
except Exception as e:
|
|
284
|
+
return {"error": f"Pivot table error: {e}"}
|
|
285
|
+
|
|
286
|
+
# Convert to serializable format
|
|
287
|
+
pivot_dict = {}
|
|
288
|
+
for idx_val in pivot.index[:50]: # Limit rows
|
|
289
|
+
row_data = {}
|
|
290
|
+
for col_val in pivot.columns[:20]: # Limit columns
|
|
291
|
+
val = pivot.loc[idx_val, col_val]
|
|
292
|
+
try:
|
|
293
|
+
row_data[str(col_val)] = round(float(val), 4) if val != 0 else 0
|
|
294
|
+
except (TypeError, ValueError):
|
|
295
|
+
row_data[str(col_val)] = str(val)
|
|
296
|
+
pivot_dict[str(idx_val)] = row_data
|
|
297
|
+
|
|
298
|
+
return {
|
|
299
|
+
"dataset": name,
|
|
300
|
+
"index": index,
|
|
301
|
+
"columns_field": columns,
|
|
302
|
+
"values_field": values,
|
|
303
|
+
"aggfunc": aggfunc,
|
|
304
|
+
"row_count": len(pivot_dict),
|
|
305
|
+
"column_values": [str(c) for c in pivot.columns[:20]],
|
|
306
|
+
"pivot": pivot_dict,
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
# ---------------------------------------------------------------------------
|
|
311
|
+
# MCP Server
|
|
312
|
+
# ---------------------------------------------------------------------------
|
|
313
|
+
mcp = FastMCP(
|
|
314
|
+
"CSV Analytics MCP",
|
|
315
|
+
instructions="Spreadsheet and CSV analysis toolkit: load files, filter/query data, compute statistics, create aggregations, pivot tables, and export chart-ready data. By MEOK AI Labs.")
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
@mcp.tool()
|
|
319
|
+
def load_csv(file_path: str, name: str = "", delimiter: str = ",", encoding: str = "utf-8", api_key: str = "") -> dict:
|
|
320
|
+
"""Load a CSV file into memory for analysis. The dataset is stored under
|
|
321
|
+
a name (defaults to filename) and can be referenced in subsequent calls.
|
|
322
|
+
|
|
323
|
+
Args:
|
|
324
|
+
file_path: Absolute path to the CSV file
|
|
325
|
+
name: Optional name for the dataset (default: filename without extension)
|
|
326
|
+
delimiter: Column delimiter (default: comma)
|
|
327
|
+
encoding: File encoding (default: utf-8)
|
|
328
|
+
"""
|
|
329
|
+
allowed, msg, tier = check_access(api_key)
|
|
330
|
+
if not allowed:
|
|
331
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
332
|
+
|
|
333
|
+
err = _check_rate_limit()
|
|
334
|
+
if err:
|
|
335
|
+
return {"error": err}
|
|
336
|
+
try:
|
|
337
|
+
return _load_csv(file_path, name, delimiter, encoding)
|
|
338
|
+
except Exception as e:
|
|
339
|
+
return {"error": str(e)}
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
@mcp.tool()
|
|
343
|
+
def query_data(name: str, filter_expr: str = "", columns: Optional[list[str]] = None,
|
|
344
|
+
sort_by: str = "", ascending: bool = True, limit: int = 100, api_key: str = "") -> dict:
|
|
345
|
+
"""Query a loaded dataset with filtering, column selection, and sorting.
|
|
346
|
+
|
|
347
|
+
Uses pandas query syntax for filters:
|
|
348
|
+
- 'age > 30'
|
|
349
|
+
- 'city == "London" and salary > 50000'
|
|
350
|
+
- 'status.isin(["active", "pending"])'
|
|
351
|
+
|
|
352
|
+
Args:
|
|
353
|
+
name: Dataset name (from load_csv)
|
|
354
|
+
filter_expr: Pandas query expression for filtering rows
|
|
355
|
+
columns: List of column names to return (default: all)
|
|
356
|
+
sort_by: Column name to sort by
|
|
357
|
+
ascending: Sort order (default: True)
|
|
358
|
+
limit: Max rows to return (default: 100)
|
|
359
|
+
"""
|
|
360
|
+
allowed, msg, tier = check_access(api_key)
|
|
361
|
+
if not allowed:
|
|
362
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
363
|
+
|
|
364
|
+
err = _check_rate_limit()
|
|
365
|
+
if err:
|
|
366
|
+
return {"error": err}
|
|
367
|
+
try:
|
|
368
|
+
return _query_data(name, filter_expr, columns, sort_by, ascending, min(limit, 500))
|
|
369
|
+
except Exception as e:
|
|
370
|
+
return {"error": str(e)}
|
|
371
|
+
|
|
372
|
+
|
|
373
|
+
@mcp.tool()
|
|
374
|
+
def describe_columns(name: str, api_key: str = "") -> dict:
|
|
375
|
+
"""Get detailed statistics for every column in a dataset:
|
|
376
|
+
- Numeric columns: mean, std, min, max, median, quartiles
|
|
377
|
+
- Categorical columns: unique count, top 5 values with frequencies
|
|
378
|
+
|
|
379
|
+
Args:
|
|
380
|
+
name: Dataset name (from load_csv)
|
|
381
|
+
"""
|
|
382
|
+
allowed, msg, tier = check_access(api_key)
|
|
383
|
+
if not allowed:
|
|
384
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
385
|
+
|
|
386
|
+
err = _check_rate_limit()
|
|
387
|
+
if err:
|
|
388
|
+
return {"error": err}
|
|
389
|
+
try:
|
|
390
|
+
return _describe_columns(name)
|
|
391
|
+
except Exception as e:
|
|
392
|
+
return {"error": str(e)}
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
@mcp.tool()
|
|
396
|
+
def aggregate(name: str, group_by: list[str], metrics: dict[str, str], api_key: str = "") -> dict:
|
|
397
|
+
"""Aggregate data with GROUP BY and compute metrics.
|
|
398
|
+
|
|
399
|
+
Supported aggregation functions: sum, mean, min, max, count, median, std, first, last, nunique
|
|
400
|
+
|
|
401
|
+
Args:
|
|
402
|
+
name: Dataset name (from load_csv)
|
|
403
|
+
group_by: List of columns to group by (e.g. ["department", "year"])
|
|
404
|
+
metrics: Dict of column -> aggregation function (e.g. {"salary": "mean", "id": "count"})
|
|
405
|
+
"""
|
|
406
|
+
allowed, msg, tier = check_access(api_key)
|
|
407
|
+
if not allowed:
|
|
408
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
409
|
+
|
|
410
|
+
err = _check_rate_limit()
|
|
411
|
+
if err:
|
|
412
|
+
return {"error": err}
|
|
413
|
+
try:
|
|
414
|
+
return _aggregate(name, group_by, metrics)
|
|
415
|
+
except Exception as e:
|
|
416
|
+
return {"error": str(e)}
|
|
417
|
+
|
|
418
|
+
|
|
419
|
+
@mcp.tool()
|
|
420
|
+
def export_chart_data(name: str, x_column: str, y_columns: list[str],
|
|
421
|
+
chart_type: str = "bar", limit: int = 50, api_key: str = "") -> dict:
|
|
422
|
+
"""Export data in a chart-ready format. Output is compatible with Chart.js,
|
|
423
|
+
Plotly, or any visualization library. Includes labels and datasets arrays.
|
|
424
|
+
|
|
425
|
+
Args:
|
|
426
|
+
name: Dataset name (from load_csv)
|
|
427
|
+
x_column: Column for the X axis / labels
|
|
428
|
+
y_columns: List of columns for Y axis / data series
|
|
429
|
+
chart_type: Suggested chart type (bar, line, scatter, pie)
|
|
430
|
+
limit: Max data points (default: 50)
|
|
431
|
+
"""
|
|
432
|
+
allowed, msg, tier = check_access(api_key)
|
|
433
|
+
if not allowed:
|
|
434
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
435
|
+
|
|
436
|
+
err = _check_rate_limit()
|
|
437
|
+
if err:
|
|
438
|
+
return {"error": err}
|
|
439
|
+
try:
|
|
440
|
+
return _export_chart_data(name, x_column, y_columns, chart_type, limit)
|
|
441
|
+
except Exception as e:
|
|
442
|
+
return {"error": str(e)}
|
|
443
|
+
|
|
444
|
+
|
|
445
|
+
@mcp.tool()
|
|
446
|
+
def pivot_table(name: str, index: str, columns: str, values: str,
|
|
447
|
+
aggfunc: str = "mean", api_key: str = "") -> dict:
|
|
448
|
+
"""Create a pivot table from a dataset. Reshapes data by grouping rows
|
|
449
|
+
and spreading column values, similar to Excel pivot tables.
|
|
450
|
+
|
|
451
|
+
Args:
|
|
452
|
+
name: Dataset name (from load_csv)
|
|
453
|
+
index: Column to use as row labels
|
|
454
|
+
columns: Column whose unique values become new columns
|
|
455
|
+
values: Column to aggregate
|
|
456
|
+
aggfunc: Aggregation function (mean, sum, count, min, max, median, std)
|
|
457
|
+
"""
|
|
458
|
+
allowed, msg, tier = check_access(api_key)
|
|
459
|
+
if not allowed:
|
|
460
|
+
return {"error": msg, "upgrade_url": "https://meok.ai/pricing"}
|
|
461
|
+
|
|
462
|
+
err = _check_rate_limit()
|
|
463
|
+
if err:
|
|
464
|
+
return {"error": err}
|
|
465
|
+
try:
|
|
466
|
+
return _pivot_table(name, index, columns, values, aggfunc)
|
|
467
|
+
except Exception as e:
|
|
468
|
+
return {"error": str(e)}
|
|
469
|
+
|
|
470
|
+
|
|
471
|
+
if __name__ == "__main__":
|
|
472
|
+
mcp.run()
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
name: csv-analytics-mcp
|
|
2
|
+
description: MCP server for csv analytics. Features load csv, query data, describe
|
|
3
|
+
columns. From MEOK AI Labs.
|
|
4
|
+
version: 1.0.0
|
|
5
|
+
tools:
|
|
6
|
+
- name: load_csv
|
|
7
|
+
description: Load a CSV file into memory for analysis. The dataset is stored under
|
|
8
|
+
parameters:
|
|
9
|
+
- name: file_path
|
|
10
|
+
type: string
|
|
11
|
+
required: true
|
|
12
|
+
- name: name
|
|
13
|
+
type: string
|
|
14
|
+
required: false
|
|
15
|
+
- name: delimiter
|
|
16
|
+
type: string
|
|
17
|
+
required: false
|
|
18
|
+
- name: encoding
|
|
19
|
+
type: string
|
|
20
|
+
required: false
|
|
21
|
+
- name: query_data
|
|
22
|
+
description: Query a loaded dataset with filtering, column selection, and sorting.
|
|
23
|
+
parameters:
|
|
24
|
+
- name: name
|
|
25
|
+
type: string
|
|
26
|
+
required: true
|
|
27
|
+
- name: filter_expr
|
|
28
|
+
type: string
|
|
29
|
+
required: false
|
|
30
|
+
- name: columns
|
|
31
|
+
type: array
|
|
32
|
+
required: false
|
|
33
|
+
- name: sort_by
|
|
34
|
+
type: string
|
|
35
|
+
required: false
|
|
36
|
+
- name: ascending
|
|
37
|
+
type: boolean
|
|
38
|
+
required: false
|
|
39
|
+
- name: limit
|
|
40
|
+
type: integer
|
|
41
|
+
required: false
|
|
42
|
+
- name: describe_columns
|
|
43
|
+
description: 'Get detailed statistics for every column in a dataset:'
|
|
44
|
+
parameters:
|
|
45
|
+
- name: name
|
|
46
|
+
type: string
|
|
47
|
+
required: true
|
|
48
|
+
- name: aggregate
|
|
49
|
+
description: Aggregate data with GROUP BY and compute metrics.
|
|
50
|
+
parameters:
|
|
51
|
+
- name: name
|
|
52
|
+
type: string
|
|
53
|
+
required: true
|
|
54
|
+
- name: group_by
|
|
55
|
+
type: array
|
|
56
|
+
required: true
|
|
57
|
+
- name: metrics
|
|
58
|
+
type: object
|
|
59
|
+
required: true
|
|
60
|
+
- name: export_chart_data
|
|
61
|
+
description: Export data in a chart-ready format. Output is compatible with Chart.js,
|
|
62
|
+
parameters:
|
|
63
|
+
- name: name
|
|
64
|
+
type: string
|
|
65
|
+
required: true
|
|
66
|
+
- name: x_column
|
|
67
|
+
type: string
|
|
68
|
+
required: true
|
|
69
|
+
- name: y_columns
|
|
70
|
+
type: array
|
|
71
|
+
required: true
|
|
72
|
+
- name: chart_type
|
|
73
|
+
type: string
|
|
74
|
+
required: false
|
|
75
|
+
- name: limit
|
|
76
|
+
type: integer
|
|
77
|
+
required: false
|
|
78
|
+
- name: pivot_table
|
|
79
|
+
description: Create a pivot table from a dataset. Reshapes data by grouping rows
|
|
80
|
+
parameters:
|
|
81
|
+
- name: name
|
|
82
|
+
type: string
|
|
83
|
+
required: true
|
|
84
|
+
- name: index
|
|
85
|
+
type: string
|
|
86
|
+
required: true
|
|
87
|
+
- name: columns
|
|
88
|
+
type: string
|
|
89
|
+
required: true
|
|
90
|
+
- name: values
|
|
91
|
+
type: string
|
|
92
|
+
required: true
|
|
93
|
+
- name: aggfunc
|
|
94
|
+
type: string
|
|
95
|
+
required: false
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import os
|
|
2
|
+
import sys
|
|
3
|
+
import unittest
|
|
4
|
+
|
|
5
|
+
# Ensure shared auth middleware is available
|
|
6
|
+
sys.path.insert(0, os.path.expanduser("~/clawd/meok-labs-engine/shared"))
|
|
7
|
+
os.chdir(os.path.dirname(os.path.abspath(__file__)) + "/..")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class TestMCPImport(unittest.TestCase):
|
|
11
|
+
def test_import_server(self):
|
|
12
|
+
"""Server module must import without errors."""
|
|
13
|
+
import server # noqa: F401
|
|
14
|
+
|
|
15
|
+
def test_mcp_or_server_object_exists(self):
|
|
16
|
+
"""FastMCP servers export 'mcp'; low-level servers export 'server'."""
|
|
17
|
+
import server as srv
|
|
18
|
+
self.assertTrue(
|
|
19
|
+
hasattr(srv, "mcp") or hasattr(srv, "server"),
|
|
20
|
+
"Expected 'mcp' or 'server' object in server.py",
|
|
21
|
+
)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class TestAuthMiddleware(unittest.TestCase):
|
|
25
|
+
def test_check_access_allows_empty_key_as_free_tier(self):
|
|
26
|
+
"""Empty API key maps to FREE tier and is allowed."""
|
|
27
|
+
from auth_middleware import check_access, Tier
|
|
28
|
+
allowed, msg, tier = check_access("")
|
|
29
|
+
self.assertTrue(allowed)
|
|
30
|
+
self.assertEqual(tier, Tier.FREE)
|
|
31
|
+
self.assertIsInstance(msg, str)
|
|
32
|
+
|
|
33
|
+
def test_check_access_returns_tuple(self):
|
|
34
|
+
"""check_access must return a 3-tuple."""
|
|
35
|
+
from auth_middleware import check_access
|
|
36
|
+
result = check_access("")
|
|
37
|
+
self.assertIsInstance(result, tuple)
|
|
38
|
+
self.assertEqual(len(result), 3)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class TestHealthEndpoint(unittest.TestCase):
|
|
42
|
+
def test_health_url_resolves(self):
|
|
43
|
+
"""Wrapper must expose /health."""
|
|
44
|
+
import urllib.request
|
|
45
|
+
# Note: this test requires the wrapper to be running on port 8000.
|
|
46
|
+
# It is skipped in CI unless the server is active.
|
|
47
|
+
try:
|
|
48
|
+
resp = urllib.request.urlopen("http://localhost:8000/health", timeout=2)
|
|
49
|
+
self.assertEqual(resp.status, 200)
|
|
50
|
+
except Exception as e:
|
|
51
|
+
self.skipTest(f"Server not running: {e}")
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
if __name__ == "__main__":
|
|
55
|
+
unittest.main()
|