eideasy-mcp by eideasy - MCP Server

eID Easy MCP Server

Prepare PDF files for electronic signing via the eID Easy API using the Model Context Protocol (MCP). This server exposes a single tool that reads a local PDF, base64-encodes it, calls the eID Easy prepare-files-for-signing endpoint, and returns a signing URL plus metadata.

Features

Secure path + filename validation (prevents traversal & invalid chars)
PDF size validation (max 20MB)
Full file content base64 upload (no partial streaming)
Robust Axios-based HTTP layer with error classification
Structured error messages suitable for LLM consumption
Graceful shutdown & logging
GitHub Actions CI (test, build, release assets)

Tool Overview

Tool Name	Description
`prepare_files_for_signing`	Reads a local PDF and prepares it for signing with eID Easy

Input Schema

{
  "folder": "<directory containing the PDF>",
  "filename": "<pdf filename (must end with .pdf)>"
}

Output Example

{
  "docId": "abc123xyz",
  "signingUrl": "https://test.eideasy.com/sign_contract_external?client_id=...&doc_id=...",
  "expiresAt": "2025-12-31T23:59:59Z"
}

Installation

git clone https://github.com/eideasy/eideasy-mcp.git
cd eideasy-mcp
npm ci
npm run build

The compiled server entrypoint will be at:

dist/mcp/server.js

Runtime Requirements

Node.js >= 20.0.0
eID Easy API credentials (client ID & secret)

Environment Variables

Variable	Required	Default	Description
`EIDEASY_CLIENT_ID`	Yes	—	Your eID Easy client ID
`EIDEASY_SECRET`	Yes	—	Your eID Easy secret
`EIDEASY_BASE_URL`	No	`https://test.eideasy.com`	API base URL (must be HTTPS unless localhost)

Example export (macOS/Linux):

export EIDEASY_CLIENT_ID="your_client_id"
export EIDEASY_SECRET="your_secret"
# Optional:
export EIDEASY_BASE_URL="https://test.eideasy.com"

Using with Claude Desktop (Reference)

See:

(Previously inlined instructions have been moved to a dedicated document for easier maintenance.)

Using with ChatGPT Desktop (OpenAI) – MCP Integration

See:

(Previously inlined instructions have been moved to a dedicated document for easier maintenance.)

Development

Scripts

Command	Description
`npm run build`	Compile TypeScript to `dist/`
`npm run dev`	Run server directly with ts-node
`npm test`	Execute Jest tests
`npm run lint`	Type-check without emit

Project Structure

src/
  mcp/
    server.ts                # MCP server bootstrap & logging
    tools/
      prepareFilesForSigning.ts
  util/
    config.ts                # Environment + security validation
    paths.ts                 # Safe path resolution & filename checks
    validation.ts            # (Rate limiter & request validation)

Testing

Run:

npm test

All tests should pass (including file-based and integration tests). Add new tests under tests/ following existing patterns.

Security Considerations

Path Traversal Protection: Filenames cannot contain .., slashes, or NUL bytes.
Filename & Directory Length Limits: Prevent resource abuse.
HTTPS Enforcement: Non-local base URLs must use HTTPS.
Secrets Not Logged: Logging avoids printing credentials.
Rate Limiting (Pluggable): validation.ts provides a simple in-memory limiter (can be expanded).

Recommendations for Production

Area	Recommendation
Secrets	Use environment injection (Docker/Kubernetes secrets, not plain files)
Logging	Pipe stderr to a structured log collector
Auditing	Track docId usage & correlate with signing events
Scaling	Wrap in a process manager (PM2 / systemd)
Hardening	Consider containerizing with a minimal base image

Release Automation

On merge to main / master:

CI runs tests (Node 20 & 22)
Builds project
Generates changelog from commits since last tag
Publishes GitHub Release with .tar.gz and .zip artifacts

To cut a new release: bump version in package.json and merge.

Example Usage (Direct CLI Test)

You can manually invoke the compiled server to verify it starts:

node dist/mcp/server.js

(Then connect via an MCP-aware client.)

FAQ

Q: Can I use this for non-PDF files?
A: Not currently; the tool enforces .pdf extension.

Q: Does it send multiple files?
A: Currently single-file only; batching could be added later.

Q: Where do I get eID Easy credentials?
A: From the eID Easy dashboard after registering your application.

Contributing

Fork & branch (feat/your-feature)
Add tests for new logic
Ensure npm test passes
Open PR with clear description