datawrapper-mcp 0.0.1__tar.gz

datawrapper_mcp-0.0.1/.clinerules

@@ -0,0 +1,188 @@
+# datawrapper-mcp Project Rules
+
+## Project Overview
+
+This is a Model Context Protocol (MCP) server that provides tools for creating Datawrapper charts through AI assistants. The server leverages Pydantic models from the datawrapper library for validation and schema generation.
+
+## Architecture
+
+### Two-Tier Tool Design
+
+1. **Chart Creation** (`create_chart`): Full control using Pydantic models
+   - Takes data, chart_type, and complete chart_config dict
+   - Validates config using Pydantic's model_validate()
+   - Allows specification of all chart properties (colors, axes, labels, etc.)
+   - Uses Pydantic class instance method: `chart.create(access_token)`
+
+2. **Schema Discovery** (`get_chart_schema`): Explore available options
+   - Returns Pydantic JSON schema for a chart type
+   - Shows all properties, types, defaults, and descriptions
+   - Enables AI to discover chart capabilities dynamically
+
+### Key Design Decisions
+
+- **Pydantic-Only**: Uses ONLY Pydantic class instance methods, never base Datawrapper client
+- **No Deprecated Methods**: Avoids dw.create_chart(), dw.publish_chart(), etc. which will be deprecated
+- **Instance Methods**: Uses chart.create(), chart.publish(), chart.update(), chart.delete()
+- **Factory Pattern**: Uses get_chart(chart_id, access_token) from datawrapper.chart_factory
+- **Type-Safe**: All configurations validated through Pydantic
+- **Flexible Data**: Supports JSON strings, list of dicts, or dict of arrays
+
+## File Structure
+
+```
+datawrapper_mcp/
+├── __init__.py          # Package initialization
+└── server.py            # Main MCP server implementation
+```
+
+## Dependencies
+
+- `datawrapper>=2.0.7`: Python wrapper for Datawrapper API with Pydantic models
+- `mcp[cli]>=1.20.0`: Model Context Protocol SDK
+- `pandas>=2.0.0`: Data manipulation for chart data
+
+## Environment Variables
+
+- `DATAWRAPPER_API_TOKEN`: Required. Get from https://app.datawrapper.de/account/api-tokens
+
+## Supported Chart Types
+
+The server supports 8 chart types from the datawrapper library:
+- `bar`: BarChart
+- `line`: LineChart
+- `area`: AreaChart
+- `arrow`: ArrowChart
+- `column`: ColumnChart
+- `multiple_column`: MultipleColumnChart
+- `scatter`: ScatterPlot
+- `stacked_bar`: StackedBarChart
+
+## Available Tools
+
+1. **create_chart**: Chart creation with full Pydantic config
+2. **get_chart_schema**: Get JSON schema for a chart type
+3. **publish_chart**: Publish chart to make it public
+4. **get_chart**: Retrieve chart information
+5. **update_chart**: Update chart data or configuration (Pydantic-validated)
+6. **delete_chart**: Delete a chart
+7. **export_chart_png**: Export chart as PNG image
+
+## MCP Resources
+
+- `datawrapper://chart-types`: Returns schemas for all chart types
+
+## Data Format
+
+The server accepts three data formats:
+
+1. **List of records** (recommended):
+   ```json
+   [{"year": 2020, "value": 100}, {"year": 2021, "value": 150}]
+   ```
+
+2. **Dict of arrays**:
+   ```json
+   {"year": [2020, 2021], "value": [100, 150]}
+   ```
+
+3. **JSON string**: String representation of either format above
+
+All formats are converted to pandas DataFrame internally.
+
+## Implementation Notes
+
+### Critical Implementation Rules
+
+**NEVER use these deprecated methods:**
+- `dw.create_chart()` - Use `chart.create(access_token)` instead
+- `dw.publish_chart()` - Use `chart.publish(access_token)` instead
+- `dw.add_data()` - Use `chart.data = df` then `chart.update(access_token)` instead
+- `dw.update_metadata()` - Use `setattr(chart, key, value)` then `chart.update(access_token)` instead
+- `dw.delete_chart()` - Use `chart.delete(access_token)` instead
+- `dw.get_chart()` - Use `get_chart(chart_id, access_token)` from datawrapper.chart_factory instead
+
+**Always use Pydantic class instance methods:**
+- Create: `chart.create(access_token=api_token)`
+- Publish: `chart.publish(access_token=api_token)`
+- Update: `chart.update(access_token=api_token)`
+- Delete: `chart.delete(access_token=api_token)`
+- Retrieve: `get_chart(chart_id, access_token=api_token)` (factory function)
+
+### Error Handling
+
+- Missing API token raises ValueError with helpful message
+- Invalid chart configs return TextContent with validation errors
+- All tool calls wrapped in try/except to return error messages
+- Chart type mapping errors provide clear feedback on supported types
+
+### Update Chart Implementation
+
+The `update_chart` tool strictly enforces Pydantic validation:
+
+1. **Retrieves existing chart** using `get_chart()` factory function (returns correct Pydantic class instance)
+2. **Gets chart class directly** from instance using `type(chart)` - no manual type mapping needed
+3. **Gets current config** using `chart.model_dump()`
+4. **Merges new config** with existing config
+5. **Validates through Pydantic** using `model_validate()` on the chart's class
+6. **Updates chart attributes** from validated model
+7. **Rejects low-level structures** like 'metadata' or 'visualize' - only accepts high-level Pydantic fields
+
+This simplified approach:
+- Eliminates manual type mapping dictionary (no exposure of low-level API types like "d3-bars-stacked")
+- Uses the chart class directly from the `get_chart()` factory function
+- Ensures chatbots cannot bypass the Pydantic abstraction layer and must use the intended API surface (title, intro, byline, source_name, etc.)
+
+### Chart Creation Flow
+
+1. Get API token from environment
+2. Convert JSON data to pandas DataFrame
+3. Get appropriate Pydantic chart class
+4. Validate configuration using model_validate()
+5. Set data on chart instance: `chart.data = df`
+6. Create chart using instance method: `chart.create(access_token)`
+7. Return chart ID and URLs using `chart.get_editor_url()`
+
+### Pydantic Integration
+
+- Uses `model_validate()` for config validation
+- Uses `model_json_schema()` for schema generation
+- Uses instance methods: `.create()`, `.publish()`, `.update()`, `.delete()`
+- Uses factory function: `get_chart(chart_id, access_token)` for retrieval
+- Uses helper methods: `.get_editor_url()`, `.get_public_url()`
+- Provides helpful validation errors from Pydantic
+
+## Testing Considerations
+
+To test the server:
+1. Set DATAWRAPPER_API_TOKEN environment variable
+2. Install package: `pip install -e .`
+3. Run server: `datawrapper-mcp`
+4. Configure MCP client to connect to server
+5. Test with AI assistant or MCP inspector
+
+## Future Enhancements
+
+Potential improvements:
+- Add more chart types as datawrapper library adds them
+- Support for map visualizations
+- Batch chart operations
+- Chart templates/presets
+- Data validation helpers
+- Export options (PNG, SVG, PDF)
+
+## Common Issues
+
+1. **Missing API token**: Set DATAWRAPPER_API_TOKEN environment variable
+2. **Invalid chart config**: Use get_chart_schema to see valid options
+3. **Data format errors**: Ensure data is JSON string, list of dicts, or dict of arrays
+4. **Type errors**: Check Pydantic validation messages for required fields
+
+## Development Workflow
+
+1. Make changes to src/datawrapper_mcp/server.py
+2. Test locally with `python -m datawrapper_mcp.server`
+3. Update README.md if adding features
+4. Update this .clinerules file with new information
+5. Run pre-commit hooks before committing
+6. Update version in src/datawrapper_mcp/__init__.py if needed

datawrapper_mcp-0.0.1/.github/dependabot.yml

@@ -0,0 +1,16 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+
+  - package-ecosystem: "github-actions"
+    directory: "/.github/workflows"
+    schedule:
+      interval: "monthly"

datawrapper_mcp-0.0.1/.github/workflows/continuous-deployment.yaml

@@ -0,0 +1,143 @@
+name: Continuous deployment
+
+on:
+  push:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-python:
+    name: Lint Python code
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v5
+
+      - id: check-ruff
+        name: Check with Ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: 'check --exit-zero --verbose'
+
+      - id: format-ruff
+        name: Format with Ruff
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: 'format --check --verbose'
+
+  mypy-python:
+    name: Check Python static typing
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v5
+
+      - id: install-uv
+        name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - id: install-python
+        name: Install Python
+        run: uv python install 3.13
+
+      - id: install-python-dependencies
+        name: Install Python dependencies
+        run: uv sync --extra mypy
+
+      - id: mypy
+        name: Run mypy
+        run: uv run mypy ./ --ignore-missing-imports
+
+  test-python:
+    name: Test Python code
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ['3.10', '3.11', '3.12', '3.13',]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - id: install-uv
+        name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - id: install-python
+        name: Install Python
+        run: uv python install ${{ matrix.python }}
+
+      - id: install-python-dependencies
+        name: Install Python dependencies
+        run: uv sync --extra test --python ${{ matrix.python }}
+
+      - id: tests
+        name: Run tests
+        run: uv run pytest --cov -sv
+
+  build:
+    name: Build release candidate
+    runs-on: ubuntu-latest
+    needs: [test-python]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - id: install-uv
+        name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - id: install-python
+        name: Install Python
+        run: uv python install 3.13
+
+      - id: build
+        name: Build releases
+        run: uv build --sdist --wheel
+
+      - id: save
+        name: Save artifact
+        uses: actions/upload-artifact@v5
+        with:
+          name: release-candidate
+          path: ./dist
+          if-no-files-found: error
+
+  release:
+    name: PyPI release
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - id: fetch
+        name: Fetch artifact
+        uses: actions/download-artifact@v6
+        with:
+          name: release-candidate
+          path: ./dist
+
+      - id: publish
+        name: Publish release
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+          verify_metadata: false

datawrapper_mcp-0.0.1/.github/workflows/docs.yaml

@@ -0,0 +1,76 @@
+name: Documentation
+
+on:
+  push:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - id: checkout
+        name: Checkout
+        uses: actions/checkout@v5
+
+      - id: install-uv
+        name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          version: "latest"
+          enable-cache: true
+          cache-dependency-glob: '**/pyproject.toml'
+
+      - id: install-python
+        name: Install Python
+        run: uv python install 3.13
+
+      - id: install-python-dependencies
+        name: Install Python dependencies
+        run: uv sync --extra docs
+
+      # - id: build-sphinx-documentation
+      #   name: Build Sphinx documentation
+      #   run: uv run sphinx-build -M html ./docs ./_build/
+
+      # - id: upload-release-candidate
+      #   name: Upload release candidate
+      #   uses: actions/upload-artifact@v5
+      #   with:
+      #     name: release-candidate
+      #     path: ./_build/html/
+
+  # deploy:
+  #   name: Deploy
+  #   runs-on: ubuntu-latest
+  #   needs: build
+  #   if: ${{ github.ref_name == 'main' }}
+  #   steps:
+  #     - name: Download release candidate
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: release-candidate
+  #         path: ./docs/
+
+  #     - id: configure-aws
+  #       name: Configure AWS Credentials
+  #       uses: aws-actions/configure-aws-credentials@v4
+  #       with:
+  #         aws-access-key-id: ${{ secrets.DOCS_AWS_ACCESS_KEY_ID }}
+  #         aws-secret-access-key: ${{ secrets.DOCS_AWS_SECRET_ACCESS_KEY }}
+  #         aws-region: ${{ secrets.DOCS_AWS_REGION }}
+
+  #     - id: upload-to-s3
+  #       name: Upload documentation to Amazon S3
+  #       uses: datadesk/delivery-deploy-action@v1
+  #       with:
+  #         bucket: ${{ secrets.DOCS_AWS_BUCKET }}
+  #         base-path: ${{ secrets.DOCS_AWS_BASE_PATH }}
+  #         dir: ./docs/
+  #         should-cache: false
+  #         use-accelerate-endpoint: false
+  #         public: true

datawrapper_mcp-0.0.1/.gitignore

@@ -0,0 +1,110 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# ruff
+.ruff_cache/
+
+# pip and uv
+./build/

datawrapper_mcp-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,47 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: 'https://github.com/pre-commit/pre-commit-hooks'
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args:
+          - '--maxkb=100000'
+      - id: fix-byte-order-marker
+      - id: check-case-conflict
+      - id: check-json
+      - id: mixed-line-ending
+      - id: check-ast
+      - id: check-merge-conflict
+
+  - repo: 'https://github.com/astral-sh/ruff-pre-commit'
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        args:
+          - '--fix'
+      - id: ruff-format
+
+  - repo: 'https://github.com/asottile/blacken-docs'
+    rev: 1.19.1
+    hooks:
+      - id: blacken-docs
+        additional_dependencies:
+          - black
+
+  - repo: 'https://github.com/asottile/pyupgrade'
+    rev: v3.19.1
+    hooks:
+      - id: pyupgrade
+        args:
+          - '--py37-plus'
+
+  - repo: 'https://github.com/pre-commit/mirrors-mypy'
+    rev: v1.15.0
+    hooks:
+      - id: mypy
+        # additional_dependencies:
+        #   - types-requests

datawrapper_mcp-0.0.1/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "ms-toolsai.jupyter"
+    ]
+}

datawrapper_mcp-0.0.1/.vscode/launch.json

@@ -0,0 +1,24 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "python": "${workspaceFolder}/.venv/bin/python"
+        },
+        {
+            "name": "Python: Debug Notebook",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "python": "${workspaceFolder}/.venv/bin/python",
+            "purpose": ["debug-in-terminal"]
+        }
+    ]
+}

datawrapper_mcp-0.0.1/.vscode/settings.json

@@ -0,0 +1,15 @@
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+    "python.terminal.activateEnvironment": true,
+    "jupyter.notebookFileRoot": "${workspaceFolder}",
+    "jupyter.interactiveWindow.cellMarker.codeRegex": "^(#\\s*%%|#\\s*\\<codecell\\>|#\\s*In\\[\\d*\\]:|#\\s*In\\[ \\]:|#\\s*cell)",
+    "jupyter.interactiveWindow.cellMarker.default": "# %%",
+    "python.analysis.extraPaths": [
+        "${workspaceFolder}"
+    ],
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}