electiondata-my-mcp 0.1.0__tar.gz

electiondata_my_mcp-0.1.0/.cursor/rules/ponytail.mdc

@@ -0,0 +1,30 @@
+# Ponytail, lazy senior dev mode
+
+You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.
+
+Before writing any code, stop at the first rung that holds:
+
+1. Does this need to be built at all? (YAGNI)
+2. Does it already exist in this codebase? Reuse the helper, util, or pattern that's already here, don't re-write it.
+3. Does the standard library already do this? Use it.
+4. Does a native platform feature cover it? Use it.
+5. Does an already-installed dependency solve it? Use it.
+6. Can this be one line? Make it one line.
+7. Only then: write the minimum code that works.
+
+The ladder runs after you understand the problem, not instead of it: read the task and the code it touches, trace the real flow end to end, then climb.
+
+Bug fix = root cause, not symptom: a report names a symptom. Grep every caller of the function you touch and fix the shared function once — one guard there is a smaller diff than one per caller, and patching only the path the ticket names leaves a sibling caller still broken.
+
+Rules:
+
+- No abstractions that weren't explicitly requested.
+- No new dependency if it can be avoided.
+- No boilerplate nobody asked for.
+- Deletion over addition. Boring over clever. Fewest files possible.
+- Shortest working diff wins, but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Question complex requests: "Do you actually need X, or does Y cover it?"
+- Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm.
+- Mark deliberate simplifications that cut a real corner with a known ceiling (global lock, O(n²) scan, naive heuristic) with a `ponytail:` comment naming the ceiling and upgrade path.
+
+Not lazy about: understanding the problem (read it fully and trace the real flow before picking a rung, a small diff you don't understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

electiondata_my_mcp-0.1.0/.cursor/rules/pytest.mdc

@@ -0,0 +1,337 @@
+---
+description: This rule file outlines comprehensive best practices for using pytest in Python projects, covering code organization, testing strategies, performance optimization, security measures, and common pitfalls to avoid.
+globs: tests/*
+---
+# Pytest Best Practices: A Comprehensive Guide
+
+This document provides a detailed guide to using pytest effectively in Python projects, covering various aspects from code organization to security considerations. It aims to provide actionable guidance for developers to improve their testing practices and build robust applications.
+
+## Library Information:
+- Name: pytest
+- Tags: development, testing, python
+
+## 1. Code Organization and Structure
+
+A well-organized codebase is crucial for maintainability and testability. Here are best practices for structuring your pytest projects:
+
+### 1.1. Directory Structure
+
+- **Separate `tests/` directory:** Keep your tests in a directory separate from your application code, typically named `tests/`. This promotes isolation and cleaner project structure.
+
+
+  my_project/
+  ├── my_app/
+  │   ├── __init__.py
+  │   ├── module1.py
+  │   └── module2.py
+  ├── tests/
+  │   ├── __init__.py
+  │   ├── test_module1.py
+  │   └── test_module2.py
+  └── pyproject.toml
+
+
+- **`src` layout (Recommended):** Consider using a `src` layout to further isolate application code from the project root. This prevents import conflicts and improves clarity.
+
+
+  my_project/
+  ├── src/
+  │   └── my_app/
+  │       ├── __init__.py
+  │       ├── module1.py
+  │       └── module2.py
+  ├── tests/
+  │   ├── __init__.py
+  │   ├── test_module1.py
+  │   └── test_module2.py
+  └── pyproject.toml
+
+
+### 1.2. File Naming Conventions
+
+- **`test_*.py` or `*_test.py`:** pytest automatically discovers test files matching these patterns.
+- **Descriptive names:** Use clear and descriptive names for your test files to indicate what they are testing (e.g., `test_user_authentication.py`).
+
+### 1.3. Module Organization
+
+- **Mirror application structure:** Structure your test modules to mirror the structure of your application code. This makes it easier to locate tests for specific modules.
+- **`__init__.py`:** Include `__init__.py` files in your test directories to ensure they are treated as Python packages.
+
+### 1.4. Component Architecture
+
+- **Isolate components:** Design your application with well-defined components that can be tested independently.
+- **Dependency injection:** Use dependency injection to provide components with their dependencies, making it easier to mock and stub external resources during testing.
+
+### 1.5. Code Splitting
+
+- **Small, focused functions:** Break down large functions into smaller, focused functions that are easier to test.
+- **Modular design:** Organize your code into modules with clear responsibilities.
+
+## 2. Common Patterns and Anti-patterns
+
+### 2.1. Design Patterns
+
+- **Arrange-Act-Assert (AAA):** Structure your tests following the AAA pattern for clarity.
+    - **Arrange:** Set up the test environment and prepare any necessary data.
+    - **Act:** Execute the code being tested.
+    - **Assert:** Verify that the code behaved as expected.
+
+  python
+  def test_example():
+      # Arrange
+      data = ...
+      expected_result = ...
+
+      # Act
+      result = function_under_test(data)
+
+      # Assert
+      assert result == expected_result
+
+
+- **Fixture factory:** Use fixture factories to create reusable test data.
+
+  python
+  import pytest
+
+  @pytest.fixture
+  def user_factory():
+      def create_user(username, email):
+          return {"username": username, "email": email}
+      return create_user
+
+  def test_create_user(user_factory):
+      user = user_factory("testuser", "test@example.com")
+      assert user["username"] == "testuser"
+
+
+### 2.2. Recommended Approaches
+
+- **Use fixtures for setup and teardown:** Fixtures help manage test dependencies and ensure a clean test environment.
+- **Parameterize tests:** Use `@pytest.mark.parametrize` to run the same test with different inputs and expected outputs, reducing code duplication.
+- **Use descriptive names for tests and fixtures:** This makes it easier to understand the purpose of each test and fixture.
+- **Single Assertion per Test:** A single assertion per test makes it easier to identify the specific failure point.
+
+### 2.3. Anti-patterns and Code Smells
+
+- **Over-reliance on fixtures:** Avoid creating too many fixtures, especially for simple data.  Use direct data definition in the test if it's not reused.
+- **Implicit dependencies:** Make dependencies explicit by passing them as arguments to your functions and tests.
+- **Testing implementation details:** Focus on testing the behavior of your code, not the implementation details.  This makes your tests more resilient to refactoring.
+- **Skipping Tests Without a Reason:** Don't skip tests without a valid reason or comment explaining why.
+
+### 2.4. State Management
+
+- **Stateless tests:** Ensure your tests are stateless and independent to avoid unexpected side effects. Each test should set up its own data and clean up after itself.
+- **Fixture scopes:** Use fixture scopes (`session`, `module`, `function`) to control the lifecycle of fixtures and manage state effectively.
+
+### 2.5. Error Handling
+
+- **Test exception handling:** Write tests to verify that your code handles exceptions correctly.
+
+  python
+  import pytest
+
+  def divide(a, b):
+      if b == 0:
+          raise ValueError("Cannot divide by zero")
+      return a / b
+
+  def test_divide_by_zero():
+      with pytest.raises(ValueError) as e:
+          divide(10, 0)
+      assert str(e.value) == "Cannot divide by zero"
+
+
+- **Use `pytest.raises`:** Use `pytest.raises` to assert that a specific exception is raised.
+- **Log errors:** Ensure your application logs errors appropriately, and consider writing tests to verify that errors are logged correctly.
+
+## 3. Performance Considerations
+
+### 3.1. Optimization Techniques
+
+- **Profile slow tests:** Use the `--durations` option to identify slow tests and optimize them.
+- **Parallel test execution:** Use `pytest-xdist` to run tests in parallel and reduce overall test execution time. `pip install pytest-xdist` then run `pytest -n auto`.  The `auto` option utilizes all available CPU cores.
+- **Caching:** Cache expensive computations to avoid redundant calculations during testing.
+
+### 3.2. Memory Management
+
+- **Resource cleanup:** Ensure your tests clean up any resources they allocate, such as temporary files or database connections.
+- **Limit fixture scope:** Use the appropriate fixture scope to minimize the lifetime of fixtures and reduce memory consumption.
+
+### 3.3. Bundle Size Optimization
+
+- **N/A:** Pytest itself doesn't directly impact bundle sizes, but your application code should be optimized separately.
+
+### 3.4. Lazy Loading
+
+- **N/A:** Lazy loading is more relevant to application code than pytest itself, but can be used within fixtures if necessary to defer initialization.
+
+## 4. Security Best Practices
+
+### 4.1. Common Vulnerabilities
+
+- **Injection attacks:** Prevent injection attacks by validating and sanitizing user inputs.
+- **Cross-site scripting (XSS):** Protect against XSS vulnerabilities by escaping user-generated content.
+- **Authentication and authorization flaws:** Implement secure authentication and authorization mechanisms to protect sensitive data.
+
+### 4.2. Input Validation
+
+- **Validate all inputs:** Validate all user inputs to ensure they conform to expected formats and ranges.
+- **Use parameterized tests:** Use parameterized tests to test input validation logic with a variety of inputs, including edge cases and invalid values.
+
+### 4.3. Authentication and Authorization
+
+- **Test authentication:** Write tests to verify that your authentication mechanisms are working correctly.
+- **Test authorization:** Write tests to verify that users only have access to the resources they are authorized to access.
+
+### 4.4. Data Protection
+
+- **Encrypt sensitive data:** Encrypt sensitive data at rest and in transit.
+- **Use secure storage:** Store sensitive data in secure storage locations with appropriate access controls.
+
+### 4.5. Secure API Communication
+
+- **Use HTTPS:** Always use HTTPS for API communication to protect data in transit.
+- **Validate API responses:** Validate API responses to ensure they are valid and haven't been tampered with.
+
+## 5. Testing Approaches
+
+### 5.1. Unit Testing
+
+- **Test individual units:** Unit tests should focus on testing individual functions, methods, or classes in isolation.
+- **Mock dependencies:** Use mocking to isolate units under test from their dependencies.
+
+### 5.2. Integration Testing
+
+- **Test interactions:** Integration tests should focus on testing the interactions between different components of your application.
+- **Use real dependencies (where appropriate):** For integration tests, it's often appropriate to use real dependencies, such as databases or external APIs, to ensure that the different components work together correctly.  Consider using test containers for database and service dependencies.
+
+### 5.3. End-to-End Testing
+
+- **Test complete workflows:** End-to-end tests should focus on testing complete user workflows, from start to finish.
+- **Use browser automation:** Use browser automation tools like Selenium or Playwright to simulate user interactions with your application.
+
+### 5.4. Test Organization
+
+- **Organize tests by feature:** Group tests by the feature they are testing to improve organization and maintainability.
+- **Use clear naming conventions:** Use clear naming conventions for your tests and test files to indicate what they are testing.
+
+### 5.5. Mocking and Stubbing
+
+- **Use `mocker` fixture:** Use the `mocker` fixture provided by the `pytest-mock` plugin for mocking and stubbing.
+- **Mock external dependencies:** Mock external dependencies, such as databases or APIs, to isolate your tests and prevent them from relying on external resources.
+- **Use `autospec=True`:** Use `autospec=True` when mocking to ensure that your mocks have the same API as the original objects. This helps prevent errors caused by incorrect mock implementations.
+
+  python
+  def test_example(mocker):
+      mock_external_api = mocker.patch("module.external_api", autospec=True)
+      mock_external_api.return_value = {"data": "test data"}
+
+
+## 6. Common Pitfalls and Gotchas
+
+### 6.1. Frequent Mistakes
+
+- **Not isolating tests:** Failing to isolate tests can lead to unpredictable results and make it difficult to debug failures.
+- **Testing implementation details:** Testing implementation details makes your tests brittle and difficult to maintain.
+- **Ignoring warnings:** Ignoring warnings from pytest can mask underlying problems in your tests.
+
+### 6.2. Edge Cases
+
+- **Empty inputs:** Test your code with empty inputs to ensure it handles them gracefully.
+- **Invalid inputs:** Test your code with invalid inputs to ensure it handles them correctly and raises appropriate exceptions.
+- **Boundary conditions:** Test your code with boundary conditions to ensure it handles them correctly.
+
+### 6.3. Version-Specific Issues
+
+- **Check release notes:** Check the release notes for each new version of pytest to be aware of any breaking changes or new features.
+- **Pin dependencies:** Pin your pytest dependency to a specific version to avoid unexpected behavior caused by updates.
+
+### 6.4. Compatibility Concerns
+
+- **Check compatibility:** Check the compatibility of pytest with other technologies you are using, such as specific versions of Python or Django.
+
+### 6.5. Debugging Strategies
+
+- **Use `--pdb`:** Use the `--pdb` option to drop into the Python debugger when a test fails.
+- **Use logging:** Use logging to add debugging information to your tests.
+- **Simplify tests:** Simplify failing tests to isolate the cause of the failure.
+
+## 7. Tooling and Environment
+
+### 7.1. Recommended Development Tools
+
+- **IDE:** Use a good IDE with pytest support, such as VS Code with the Python extension, PyCharm, or Sublime Text with the appropriate plugins.
+- **pytest-watch:** Use `pytest-watch` for automatic test rerunning on file changes. `pip install pytest-watch`, then run `ptw`.
+
+### 7.2. Build Configuration
+
+- **Use `pyproject.toml`:** Use a `pyproject.toml` file to configure your pytest settings.
+
+  toml
+  [tool.pytest.ini_options]
+  addopts = [
+      "--cov=my_app",
+      "--cov-report term-missing",
+      "-v",
+  ]
+  testpaths = [
+      "tests",
+  ]
+
+
+### 7.3. Linting and Formatting
+
+- **Use `flake8-pytest-style`:** Use the `flake8-pytest-style` plugin to enforce pytest-specific coding standards.  `pip install flake8 flake8-pytest-style`
+- **Use `black` or `autopep8`:** Use a code formatter like `black` or `autopep8` to ensure consistent code formatting.  `pip install black`, then run `black .`
+
+### 7.4. Deployment
+
+- **Include tests in your deployment pipeline:** Ensure your tests are run as part of your deployment pipeline to prevent regressions.
+- **Use a dedicated test environment:** Use a dedicated test environment to avoid interfering with your production environment.
+
+### 7.5. CI/CD Integration
+
+- **Integrate with CI/CD:** Integrate pytest with your CI/CD system, such as GitHub Actions, GitLab CI, or Jenkins, to automatically run your tests on every commit.
+
+  Example GitHub Actions workflow (`.github/workflows/test.yml`):
+
+
+  name: Test
+  on:
+    push:
+      branches: [ main ]
+    pull_request:
+      branches: [ main ]
+  jobs:
+    build:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v3
+        - name: Set up Python 3.10
+          uses: actions/setup-python@v3
+          with:
+            python-version: "3.10"
+        - name: Install dependencies
+          run: |
+            python -m pip install --upgrade pip
+            pip install pytest pytest-cov flake8 flake8-pytest-style black
+            pip install -e .  # Install your project in editable mode
+        - name: Lint with flake8
+          run: |
+            flake8 .
+        - name: Test with pytest
+          run: |
+            pytest --cov --cov-report xml
+        - name: Upload coverage to Codecov
+          uses: codecov/codecov-action@v3
+          with:
+            token: ${{ secrets.CODECOV_TOKEN }}
+            flags: unittests
+            env_vars: OS,PYTHON
+            name: codecov-pytest
+
+
+By following these best practices, you can write effective and maintainable tests with pytest, improving the quality and reliability of your Python applications.---
+alwaysApply: true
+---

electiondata_my_mcp-0.1.0/.cursor/rules/uv.mdc

@@ -0,0 +1,29 @@
+---
+description: Install Python packages, access Python CLI, run python code and scripts, execute Python commands, and manage Python environments. Use uv run for all Python execution instead of direct python commands.
+alwaysApply: false
+---
+
+# Python Package Management with uv
+
+Use uv exclusively for Python package management in all projects.
+
+## Package Management Commands
+
+- All Python dependencies **must be installed, synchronized, and locked** using uv
+- Never use pip, pip-tools, poetry, or conda directly for dependency management
+
+Use these commands
+
+- Install dependencies: `uv add <package>`
+- Remove dependencies: `uv remove <package>`
+- Sync dependencies: `uv sync`
+
+## Running Python Code
+
+- Run a Python script with `uv run <script-name>.py`
+- Run Python tools like Pytest with `uv run pytest` or `uv run ruff`
+- Launch a Python repl with `uv run python`---
+alwaysApply: true
+------
+alwaysApply: true
+---

electiondata_my_mcp-0.1.0/.cursor/skills/query-electiondatamy-api/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: query-electiondatamy-api
+description: Queries and analyzes Malaysian election data through the ElectionData.MY API. Use when the user asks for candidates, seats, parties, coalitions, elections, by-elections, contest results, turnout, majorities, or vote shares from ElectionData.MY.
+---
+
+# Query ElectionData.MY API
+
+Use the v1 API to answer focused questions about Malaysian election data. Read [reference.md](reference.md) before choosing endpoints or parameters.
+
+## Scope
+
+Use the API for focused, dynamic queries. Recommend the ElectionData.MY data lake instead when the user needs:
+
+- bulk analysis or the full dataset;
+- geospatial or boundary files;
+- local analytical workflows better served by static files.
+
+## Authentication and safety
+
+- Base URL: `https://api.electiondata.my/v1`
+- Only `GET` requests are supported.
+- Every request requires `Authorization: Bearer <API key>`.
+- Use the `ELECTIONDATAMY_API_KEY` environment variable. Check that it exists without printing it:
+
+```bash
+test -n "$ELECTIONDATAMY_API_KEY"
+```
+
+- If it is missing, ask the user to set it in their terminal. Do not ask them to paste the key into chat.
+- Never print, persist, commit, or interpolate the key as a literal.
+
+## Query workflow
+
+1. Translate the question into the entity, scope, election type, and date needed.
+2. Select the endpoint chain from the reference.
+3. When an identifier is unknown, call the relevant dropdown endpoint first. Do not guess UIDs, slugs, election identifiers, seat names, states, or dates.
+4. Pass identifiers returned by discovery endpoints exactly as documented:
+   - Candidate queries use `uid`.
+   - Party queries use the selected entry's `maps_to` as `uid`, never its historical `uid`.
+   - Result detail queries reuse `seat`, `state`, and `date` from a companion endpoint without transformation.
+5. URL-encode every query parameter. Prefer `curl --get --data-urlencode`.
+6. Inspect the complete response before filtering or aggregating it.
+7. Answer concisely, naming the endpoint and query scope used. Clearly separate returned fields from calculations or interpretation.
+
+## Request pattern
+
+```bash
+curl --silent --show-error --fail-with-body --get \
+  "https://api.electiondata.my/v1/<endpoint>" \
+  --header "Authorization: Bearer ${ELECTIONDATAMY_API_KEY}" \
+  --data-urlencode "parameter=value"
+```
+
+For an endpoint without parameters, omit `--get` and `--data-urlencode`.
+
+## Endpoint chaining
+
+- Candidate lookup: `/candidates/dropdown` → `/candidates?uid=...` → optionally `/results`
+- Seat history: `/seats/dropdown` → `/seats/results?slug=...` → optionally `/results`
+- Party or coalition history: `/parties/dropdown` → `/parties/results`
+- Election overview: `/elections/dropdown` → one or more of `/elections/by_party`, `/elections/by_seat`, `/elections/stats`
+- By-election list: `/byelections` → optionally `/results`
+- Contest detail: obtain `seat`, `state`, and `date` from a companion endpoint → `/results`
+
+## Interpretation rules
+
+- Treat ISO dates as polling dates unless the field explicitly describes a boundary-change event.
+- Percentage fields are already percentages; do not multiply them by 100.
+- `won_uncontested` can legitimately produce zero or null vote statistics.
+- In party queries, `{"results":[]}` means no contests in that scope, not an API error.
+- With seat `lineage=true`, distinguish election rows by the presence of `election_name`; rows without it are boundary-change events.
+- Preserve the API's `parlimen` and `dun` values when filtering.
+- Do not infer current party identity from `known_as`; explain historical names and canonical mappings when relevant.
+
+## Errors
+
+- `400`: missing or invalid parameters, invalid combinations, malformed date, or missing version prefix.
+- `401`: missing or invalid API key.
+- `404`: unknown endpoint or no matching resource.
+- `405`: method other than `GET`.
+- `500`: server-side failure.
+
+Error bodies contain an `error` field. Report the useful message, correct the request when possible, and do not silently reinterpret an invalid query.
+
+## Answer quality
+
+- State material filters such as state, election, election type, lineage mode, and date.
+- Include units for vote counts, seats, turnout, and percentages.
+- For comparisons, verify that scopes and denominators match.
+- Mention missing or null data rather than silently dropping it.
+- Do not claim the API is real-time; dropdown datasets update around election-related publication events described in the docs.

electiondata_my_mcp-0.1.0/.cursor/skills/query-electiondatamy-api/reference.md

@@ -0,0 +1,164 @@
+# ElectionData.MY v1 reference
+
+Base URL: `https://api.electiondata.my/v1`
+
+All endpoints are authenticated `GET` requests.
+
+## Candidates
+
+### `/candidates/dropdown`
+
+No parameters. Returns an array of candidates ordered by contests, with:
+
+- `uid`, `name`
+- `c` contests, `w` wins, `l` losses
+
+Use `uid` in `/candidates`.
+
+### `/candidates`
+
+Required: `uid`
+
+Returns an array ordered newest to oldest. Each row identifies the candidate, election, seat, state, party and coalition, votes, vote percentage, polling date, and result.
+
+Result values: `won`, `won_uncontested`, `lost`, `lost_deposit`.
+
+## Seats
+
+### `/seats/dropdown`
+
+No parameters. Response: `{ "seats": [...] }`
+
+Each row contains:
+
+- `seat`: full current seat name
+- `slug`: identifier for `/seats/results`
+- `type`: `parlimen` or `dun`
+
+### `/seats/results`
+
+Required: `slug`
+
+Optional: `lineage=true|false` (default `false`)
+
+Response: `{ "results": [...] }`, newest first.
+
+Election rows include `election_name`, `seat`, `state`, `date`, winner `name`, party and coalition identifiers, majority, and turnout.
+
+With `lineage=true`, the array also contains boundary-change rows with `date`, `change_en`, and `change_ms`. A row with `election_name` is an election result; a row without it is a boundary-change event.
+
+## Parties and coalitions
+
+### `/parties/dropdown`
+
+No parameters. Response: `{ "data": [...] }`
+
+Each row contains `type`, `uid`, `maps_to`, `acronym`, `name_en`, and `name_bm`.
+
+Historical names may have legacy UIDs. Always pass `maps_to`, not `uid`, to `/parties/results`.
+
+### `/parties/results`
+
+Required:
+
+- `type`: `party` or `coalition`
+- `uid`: the dropdown row's `maps_to`
+- `state`
+- `election_type`: `parlimen` or `dun`
+
+Valid states:
+
+`Malaysia`, `Semenanjung`, `Johor`, `Kedah`, `Kelantan`, `Melaka`, `Negeri Sembilan`, `Pahang`, `Perak`, `Perlis`, `Pulau Pinang`, `Sabah`, `Sarawak`, `Selangor`, `Terengganu`, `W.P. Kuala Lumpur`, `W.P. Labuan`, `W.P. Putrajaya`
+
+`dun` is invalid for `Malaysia`, `Semenanjung`, and every `W.P. *` state.
+
+Response: `{ "results": [...] }`, newest first. Rows contain historical identity (`known_as_uid`, `known_as`), election and date, seats contested and won, seat percentages, votes, and vote percentage. An empty `results` array is valid.
+
+## Elections
+
+### `/elections/dropdown`
+
+No parameters. Response: `{ "elections": [...] }`
+
+Each row contains `state`, `type`, `election`, and `date`. Pass `state` and `election` directly to the following election endpoints.
+
+### `/elections/by_party`
+
+Required: `state`, `election`
+
+Response: `{ "by_party": [...] }`, ordered by votes descending. Rows include party and coalition identifiers, seats contested and won, total seats, seat percentages, votes, total valid votes, and vote percentage.
+
+### `/elections/by_seat`
+
+Required: `state`, `election`
+
+Response: `{ "by_seat": [...] }`, one row per constituency. Rows contain the seat, date, winner, winning and losing parties and coalitions, candidate count, registered voters, turnout, majority, and rejected-vote statistics.
+
+### `/elections/stats`
+
+Required: `state`, `election`
+
+Response: `{ "stats": [<single aggregate row>] }`
+
+The row contains registered voters, turnout, turnout percentage, rejected votes, rejected-vote percentage, and candidate count.
+
+## By-elections
+
+### `/byelections`
+
+No parameters. Response: `{ "data": [...] }`, newest first.
+
+Each row contains `seat`, `state`, `date`, winner, party and coalition identifiers, registered voters, turnout, rejected votes, majority, and corresponding percentages.
+
+Use a row's `seat`, `state`, and `date` to request full contest details from `/results`.
+
+## Contest details
+
+### `/results`
+
+Required:
+
+- `seat`
+- `state`
+- `date` in `YYYY-MM-DD`
+
+Obtain all three values from candidates, seats, elections, or by-elections responses and pass them through unchanged.
+
+Response:
+
+- `ballot`: candidates ordered by votes descending, with party, coalition, votes, vote percentage, and result
+- `stats`: a one-row array containing date, registered voters, turnout, rejected votes, majority, and corresponding percentages
+
+For uncontested wins, vote counts may be zero and percentage statistics may be null.
+
+## Common examples
+
+Find a candidate's history:
+
+```bash
+curl --silent --show-error --fail-with-body --get \
+  "https://api.electiondata.my/v1/candidates" \
+  --header "Authorization: Bearer ${ELECTIONDATAMY_API_KEY}" \
+  --data-urlencode "uid=CMVBA"
+```
+
+Get election results by party:
+
+```bash
+curl --silent --show-error --fail-with-body --get \
+  "https://api.electiondata.my/v1/elections/by_party" \
+  --header "Authorization: Bearer ${ELECTIONDATAMY_API_KEY}" \
+  --data-urlencode "state=Malaysia" \
+  --data-urlencode "election=GE-15"
+```
+
+Get one contest:
+
+```bash
+curl --silent --show-error --fail-with-body --get \
+  "https://api.electiondata.my/v1/results" \
+  --header "Authorization: Bearer ${ELECTIONDATAMY_API_KEY}" \
+  --data-urlencode "seat=P.001 Padang Besar" \
+  --data-urlencode "state=Perlis" \
+  --data-urlencode "date=2022-11-19"
+```

electiondata_my_mcp-0.1.0/.env.example

@@ -0,0 +1 @@
+ELECTIONDATAMY_API_KEY=""