CONTRIBUTING

Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Issues and PRs

If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.

We'd also love PRs. If you're thinking of a large PR, we advise opening up an issue first to talk about it, though! Look at the links below if you're not sure how to open a PR.

Development Environment Setup

Prerequisites

Requirement	Minimum Version	Check
Node.js	26.0.0	`node --version`
npm	10.0.0	`npm --version`
Git	2.x	`git --version`

Initial Setup

# 1. Fork the repository, then clone your fork
git clone https://github.com/<your-username>/European-Parliament-MCP-Server.git
cd European-Parliament-MCP-Server

# 2. Install dependencies (uses package-lock.json for reproducibility)
npm install

# 3. Verify build works
npm run build

# 4. Run all unit tests to confirm your environment is healthy
npm test

# 5. Optional: run type-checking separately
npm run type-check

Development Commands

# Start the server in watch mode (auto-recompile on change)
npm run dev

# Run unit tests in watch mode
npm run test:watch

# Run unit tests with coverage report
npm run test:coverage

# Lint source files
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Check code formatting
npm run format

# Check for dead code / unused exports
npm run knip

# Security audit
npm audit

# License compliance check
npm run test:licenses

Environment Variables

Create a .env.test file for integration testing:

# Set to 'true' to run tests against the real EP API (rate-limited)
EP_INTEGRATION_TESTS=false

# Optional: override API base URL for testing against a mirror
EP_API_URL=https://data.europarl.europa.eu/api/v2

⚠️ Never commit .env files — they are listed in .gitignore.

Branch Naming Conventions

All branches must follow the pattern: <type>/<short-description>

Type	Purpose	Example
`feature/`	New functionality	`feature/add-budget-tool`
`fix/`	Bug fix	`fix/rate-limiter-race-condition`
`docs/`	Documentation only	`docs/improve-jsdoc-getMEPs`
`chore/`	Maintenance, deps, CI	`chore/upgrade-vitest-4`
`test/`	Test improvements	`test/add-e2e-coalition-tool`
`perf/`	Performance improvements	`perf/cache-key-normalization`
`security/`	Security fixes	`security/upgrade-undici`

Submitting a Pull Request

Fork and clone the repository.
Configure and install the dependencies: npm install
Make sure the tests pass on your machine: npm test
Create a new branch: git checkout -b feature/my-branch-name
Make your change, add tests, and make sure the tests still pass.
Push to your fork and submit a pull request.
Pat yourself on the back and wait for your pull request to be reviewed and merged.

Pull Request Guidelines

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

Write and update tests - Maintain 80%+ code coverage (95% for security code)
Keep your changes focused - If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
Write a good commit message - Follow Conventional Commits
Follow code style - Run npm run lint and npm run format before committing
Update documentation - Keep README.md and other docs up to date with your changes

Automatic PR Labeling

When you submit a pull request, our automated labeler will automatically apply labels based on the files you've changed:

🔌 MCP Development Labels

mcp-tools - Changes to MCP tool implementations (src/tools/)
mcp-resources - Changes to MCP resources (src/resources/)
mcp-prompts - Changes to MCP prompts (src/prompts/)
mcp-protocol - MCP protocol changes

🏛️ European Parliament Labels

ep-api - European Parliament API integration
ep-data - European Parliament data handling
meps - MEP-related changes
plenary - Plenary session features
committees - Committee features
documents - Document handling

🚀 General Labels

feature - New features or functionality
enhancement - Improvements to existing features
bug - Bug fixes
documentation - Documentation updates
dependencies - Dependency updates
security - Security improvements
performance - Performance optimizations
testing - Test improvements

🔒 Compliance Labels

gdpr - GDPR compliance changes
isms-compliance - ISMS policy compliance
security - Security enhancements

You can also manually add labels by including them in your PR description using checkboxes:

- [x] 🚀 New Feature/Enhancement
- [x] 🔌 MCP Tools
- [x] 🏛️ European Parliament API

Commit Message Format

We follow Conventional Commits specification:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, missing semicolons, etc)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
build: Changes to build system or dependencies
ci: CI/CD changes
chore: Other changes that don't modify src or test files

Examples:

feat(mcp-tools): add getMEPs tool for fetching MEP information

fix(ep-api): handle rate limiting in European Parliament API calls

docs: update README with new MCP tools documentation

test: add unit tests for plenary session tools

build(deps): update @modelcontextprotocol/sdk to v1.0.5

Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocked you.

How to Add a New MCP Tool

See docs/TOOL_DEVELOPMENT.md for the full step-by-step guide. Here is the quick summary:

Step 1 — Create the tool file

# Create src/tools/myNewTool.ts
# Use an existing tool (e.g., getMEPs.ts) as a template

Step 2 — Add a Zod schema

Add the input schema to src/schemas/europeanParliament.ts:

export const MyNewToolSchema = z.object({
  subjectId: z.string().min(1).max(200).describe('Subject identifier'),
  limit: z.number().int().min(1).max(100).default(50),
});

Step 3 — Implement the handler

Follow the two-layer error pattern:

export async function handleMyNewTool(args: unknown): Promise<ToolResult> {
  const params = MyNewToolSchema.parse(args);  // Layer 1: Zod validation
  try {
    const result = await epClient.someMethod(params);
    return buildToolResponse(result);
  } catch (error) {
    const msg = error instanceof Error ? error.message : 'Unknown error';
    throw new Error(`Failed to fetch data: ${msg}`);
  }
}

Step 4 — Export metadata and register

export const myNewToolMetadata = {
  name: 'my_new_tool',
  description: 'One paragraph explaining what this tool does and its parameters.',
  inputSchema: { type: 'object' as const, properties: { ... } },
};

Then add the import and routing case to the server's tool registry.

Step 5 — Write tests

Create src/tools/myNewTool.test.ts covering:

✅ Valid input → correct ToolResult
✅ API failure → descriptive error thrown
✅ Invalid/empty input → ZodError thrown
✅ Default parameter values applied

OSINT tools only: any tool registered with category: 'osint' is automatically enrolled in the cross-tool contract suite (tests/integration/osint/contract.test.ts) and the per-tool golden-snapshot suite (tests/integration/osint/snapshots.test.ts). Add a minimal-valid input entry to OSINT_TOOL_INPUTS in tests/fixtures/osint/index.ts (single source of truth — both suites import from it), and ensure your tool follows the no-silent-zero policy (see below).

No-silent-zero policy (OSINT tools)

Every OSINT tool returns the OsintStandardOutput envelope: confidenceLevel, methodology, dataFreshness, sourceAttribution, dataQualityWarnings. The policy: no numeric field outside dataQualityWarnings may be silently zero because a data source was unavailable. When a source is missing or empty, the tool SHOULD either:

Degrade confidenceLevel to LOW or MEDIUM and push a human-readable entry into dataQualityWarnings explaining the unavailability, OR
Keep confidenceLevel = HIGH only when the remaining data is sufficient to fully back every non-warning numeric metric in the payload.

The contract test enforces the observable invariant: if confidenceLevel is LOW/MEDIUM, dataQualityWarnings MUST be non-empty. A degraded confidence level with no warning fails the test. See INTEGRATION_TESTING.md § "OSINT QA Harness" for the full policy.

Refreshing OSINT golden snapshots

The golden-snapshot suite (tests/integration/osint/snapshots.test.ts) diff-asserts every OSINT tool's response against a checked-in snapshot for two fixture variants (empty-path, hot-path) — 30 snapshots total. A diff means a methodology change has occurred (scoring weight moved, classification bucket changed, attribution list re-ordered).

If the diff is intentional:

# Regenerate the affected snapshots
npm run test:osint:snapshots -- -u

# Inspect every diff (snapshots live at tests/integration/osint/__snapshots__/)
git diff tests/integration/osint/__snapshots__/

# Acknowledge the refresh in your PR
#   → tick "OSINT snapshot refresh acknowledged" in PULL_REQUEST_TEMPLATE.md

Reviewer guidance: never approve a PR that touches tests/integration/osint/__snapshots__/ without the acknowledgement checkbox ticked AND a justification for the methodology change in the PR description. Snapshot diffs are the regression-detection line for OSINT scoring; silently rubber-stamping them defeats the purpose of the suite. See INTEGRATION_TESTING.md § "OSINT QA Harness — Golden Snapshots" for the full workflow.

Mutation testing (OSINT)

The contract suite catches structural envelope violations but cannot detect logic regressions in scoring/anomaly methodology. The dedicated osint-qa CI workflow runs Stryker against the 15 OSINT tool files plus their seven shared utilities (votingBaseline.ts, graphAlgorithms.ts, networkVotingSimilarity.ts, effectivenessAggregator.ts, lifecycleStatistics.ts, doceoMepAggregator.ts, politicalGroupNormalization.ts).

Run the mutation suite locally:

# Full mutation run (≈10–15 min on a laptop, scoped per stryker.config.json)
npm run test:mutation

# CI-equivalent invocation
npm run test:mutation:ci

Reports are written to builds/stryker/mutation-report.html and .json.

Acceptable surviving mutants:

Log-string mutants — string-literal mutations inside console.error / auditSink log messages have no observable effect and may be left surviving.
Defensive ?? 0 / || [] fallbacks unreachable from existing fixtures — annotate with // Stryker disable next-line and a one-line justification rather than adding contrived tests.
Pure dev-time guard clauses (e.g. type-narrowing branches that mirror Zod validation) — same triage.

Everything else — boundary mutations on percentiles, anomaly thresholds, voting-similarity scores, lifecycle bucketing, coalition strength tiers, sentiment classification cuts — must be killed by a test. If a survivor lands on a DOCEO-touching tool (assessMepInfluence, detectVotingAnomalies, sentimentTracker, networkAnalysis, analyzeCoalitionDynamics), add a regression test before merging.

The mutation job is currently continue-on-error: true while we observe the baseline score on main. Once stable, thresholds.break in stryker.config.json will be promoted from null to 70, making the job a required check.

DI Container Pattern

The server uses a lightweight Dependency Injection (DI) container defined in src/di/.

Tokens (`src/di/tokens.ts`)

import { TOKENS } from './di/tokens.js';

// Available tokens:
TOKENS.EPClient        // EuropeanParliamentClient singleton
TOKENS.RateLimiter     // Token-bucket rate limiter
TOKENS.MetricsService  // Performance metrics collector
TOKENS.AuditLogger     // GDPR-compliant audit logger
TOKENS.HealthService   // Server health-check service

Using the Container

import { createDefaultContainer } from './di/container.js';
import { TOKENS } from './di/tokens.js';
import type { MetricsService } from './services/MetricsService.js';

// In server startup:
const container = createDefaultContainer();

// Resolve a singleton:
const metrics = container.resolve<MetricsService>(TOKENS.MetricsService);
metrics.recordRequest('get_meps', 42);

When to Use the DI Container

New services (e.g., a caching service, an alerting service) should be registered as singletons via createDefaultContainer() in src/di/container.ts
Tools use the shared epClient singleton imported directly from src/clients/europeanParliamentClient.ts (it is wired into the container internally)
Unit tests can create isolated containers or mock individual tokens

Testing Requirements

All PRs must maintain these coverage thresholds:

Metric	Minimum
Lines	80%
Statements	80%
Functions	80%
Branches	70%
Security-critical code	95%

Running Test Suites

# Unit tests (fast, no external dependencies)
npm run test:unit

# Unit tests with coverage report
npm run test:coverage

# Integration tests against real EP API (opt-in)
EP_INTEGRATION_TESTS=true npm run test:integration

# Integration tests with fixture capture
EP_INTEGRATION_TESTS=true EP_SAVE_FIXTURES=true npm run test:integration

# End-to-end tests via MCP stdio client
npm run test:e2e

# Performance benchmarks
npm run test:performance

# All test suites
npm run test:all

# Watch mode for TDD
npm run test:watch

Test File Locations

src/tools/myTool.test.ts       # Unit tests co-located with tool
tests/integration/             # Integration tests (EP API)
tests/e2e/                     # End-to-end MCP client tests
tests/performance/             # Performance benchmarks
tests/fixtures/                # Shared mock data
tests/helpers/                 # Test utilities (retry, measureTime, etc.)

Code Review Standards

Reviewers will check:

Correctness — Does the code do what it claims?
Test coverage — Are all happy paths and error paths covered?
Type safety — No any, no unvalidated unknown beyond the handler entry point
Error handling — Errors sanitized, no internal details leaked
Documentation — JSDoc complete with @param, @returns, @throws, @example
Security — Input validated with Zod, ISMS policy tags present
Performance — No unnecessary API calls; cache hits for repeated queries
Consistency — Follows existing patterns (buildToolResponse, schema naming, etc.)

Security Review Checklist for PRs

Before requesting a review on any PR touching src/:

[ ] No hardcoded credentials, tokens, or API keys
[ ] All user inputs validated with Zod (.parse(args) as first handler line)
[ ] String inputs have explicit min() and max() length constraints
[ ] Error messages don't expose stack traces, internal URLs, or secrets
[ ] No console.log of sensitive data (MEP personal data, error internals)
[ ] New dependencies checked with npm audit — zero high/critical findings
[ ] New dependencies are from approved license list (MIT, Apache-2.0, BSD, ISC)
[ ] ISMS policy tags added to JSDoc: SC-002 (Input Validation), AC-003 (Least Privilege)
[ ] If touching auth/rate-limiting: 95%+ security code coverage maintained

Supply Chain Security

This project generates a Software Bill of Materials (SBOM) for every release and implements SLSA Level 3 build provenance to ensure supply chain transparency and security.

Build Attestations (SLSA Level 3):

Cryptographic proof of build integrity for all release artifacts
Non-falsifiable provenance using GitHub Sigstore
Verify with: gh attestation verify <artifact> --owner Hack23 --repo European-Parliament-MCP-Server
npm packages published with provenance: npm view european-parliament-mcp-server dist.attestations

SBOM Generation:

All direct and transitive dependencies
Package versions, licenses, and checksums
Vulnerability scanning results
Generated in SPDX 2.3+ and CycloneDX formats
Quality validated with SBOMQS (minimum score 7.0/10)
Vulnerability scanned with Grype

Accessing Security Artifacts:

Download from latest release
SBOM: sbom.spdx.json and sbom.cyclonedx.json
Provenance: provenance.intoto.jsonl
Checksums: checksums.txt

For more details, see:

Contributing

Issues and PRs

Development Environment Setup

Prerequisites

Initial Setup

Development Commands

Environment Variables

Branch Naming Conventions

Submitting a Pull Request

Pull Request Guidelines

Automatic PR Labeling

🔌 MCP Development Labels

🏛️ European Parliament Labels

🚀 General Labels

🔒 Compliance Labels

Commit Message Format

How to Add a New MCP Tool

Step 1 — Create the tool file

Step 2 — Add a Zod schema

Step 3 — Implement the handler

Step 4 — Export metadata and register

Step 5 — Write tests

No-silent-zero policy (OSINT tools)

Refreshing OSINT golden snapshots

Mutation testing (OSINT)

DI Container Pattern

Tokens (`src/di/tokens.ts`)

Using the Container

When to Use the DI Container

Testing Requirements

Running Test Suites

Test File Locations

Code Review Standards

Security Review Checklist for PRs

Supply Chain Security

Resources

Settings

On This Page

Contributing

Issues and PRs

Development Environment Setup

Prerequisites

Initial Setup

Development Commands

Environment Variables

Branch Naming Conventions

Submitting a Pull Request

Pull Request Guidelines

Automatic PR Labeling

🔌 MCP Development Labels

🏛️ European Parliament Labels

🚀 General Labels

🔒 Compliance Labels

Commit Message Format

How to Add a New MCP Tool

Step 1 — Create the tool file

Step 2 — Add a Zod schema

Step 3 — Implement the handler

Step 4 — Export metadata and register

Step 5 — Write tests

No-silent-zero policy (OSINT tools)

Refreshing OSINT golden snapshots

Mutation testing (OSINT)

DI Container Pattern

Tokens (src/di/tokens.ts)

Using the Container

When to Use the DI Container

Testing Requirements

Running Test Suites

Test File Locations

Code Review Standards

Security Review Checklist for PRs

Supply Chain Security

Resources

Settings

On This Page

Tokens (`src/di/tokens.ts`)