EPC Tender Screening MCP

An MCP-only server for evidence-based EPC tender screening.

This project lets MCP-compatible AI agents:

• run a full screen_tender workflow,

• extract tender requirements from uploaded tender text,

• match requirements against a company profile,

• generate compliance matrices,

• produce bid/no-bid advisory memos,

• search explicit public tender source URLs,

• search local historical proposal examples for grounding.

The project is designed as a clean public MCP repository. It does not include private company documents, credentials, UI pages, or production tender archives.

Why This Exists

Tender teams spend significant time reading long procurement documents, checking eligibility, finding supporting evidence, and deciding whether to bid. This MCP server gives AI agents a structured tool layer for that workflow while keeping the final decision human-reviewed.

Related MCP server: TenderAI

Tools

System Design

Requirements

Functional

• Expose requirement extraction, company matching, compliance matrices, advisory bid/no-bid memos, and the end-to-end screen_tender workflow to MCP clients.

• Support local stdio clients and remote Streamable HTTP connectors.

Non-functional

• Attach an evidence trace to compliance rows and keep fixture-based evals deterministic.

• Restrict discovery to configured public tender URLs and require human review of recommendations.

High-Level Architecture

MCP client → stdio transport ─┐
            HTTP /api/mcp ────┴→ MCP server
                                  ├→ connected tender/profile text
                                  ├→ allowlisted public sources
                                  ├→ local JSON proposal examples
                                  └→ screen_tender → matrix + advisory memo
OAuth-compatible connector routes: /oauth/* and /.well-known/*

The source currently registers 11 MCP tools, including screen_tender. Connector routes provide OAuth-compatible metadata and demo flows; production deployments should configure real authorization.

Data Model / API Contract

Scale and Reliability

• Public tender search fetches configured sources, blocks common private-host forms, applies a 12-second timeout, and caps response text at 1 MB.

• The workflow is synchronous and file-backed; no shared database or job queue is configured.

• GitHub Actions runs install, lint, build, and deterministic MCP evals. The current workflow does not run npm audit.

Trade-offs

What to Revisit as It Grows

• Validate resolved IP addresses as well as host strings before fetching public sources.

• Add npm audit to CI alongside lint, build, and evals.

• Replace demo OAuth behavior with per-user authorization and shared storage.

Quick Start

npm install
npm run dev

Open:

http://localhost:3000

The root URL returns JSON metadata only. There is no UI.

The Streamable HTTP MCP endpoint is:

http://localhost:3000/api/mcp

The root URL returns JSON metadata only:

curl http://localhost:3000

For local connector testing without auth:

MCP_REQUIRE_AUTH=false npm run dev

On Windows PowerShell:

$env:MCP_REQUIRE_AUTH="false"
npm run dev

Stdio MCP

npm run mcp:stdio

Example Claude Desktop style config:

{
  "mcpServers": {
    "epc-tender-screening": {
      "command": "npm",
      "args": ["run", "mcp:stdio"],
      "cwd": "/absolute/path/to/epc-tender-screening-mcp-showcase"
    }
  }
}

Remote Connector Auth

The repo includes a demo OAuth shim for hosted connector experiments.

Set:

MCP_PUBLIC_BASE_URL=https://your-domain.example
MCP_API_KEY=replace-this-token

Connector values:

MCP URL: https://your-domain.example/api/mcp
Authorization URL: https://your-domain.example/oauth/authorize
Token URL: https://your-domain.example/oauth/token
Client ID: epc-tender-demo-client
Client Secret: epc-tender-demo-secret
Scope: mcp tender:read tender:screen

For production, replace the demo OAuth shim with real OAuth and per-user authorization.

Demo token auth is disabled by default in production. For temporary hosted demos only, set:

MCP_ALLOW_DEMO_AUTH=true
MCP_DEMO_ACCESS_TOKEN=replace-this-demo-token

Do not use the default demo token for a public deployment.

ChatGPT Upload Workflow

Upload company profile and tender files to ChatGPT, then ask:

Extract text from the uploaded company profile and tender files.
Call screen_tender with tender_text and company_profile_text.
Summarize the recommendation, red flags, missing documents, and next human actions.

For one-shot analysis without saving:

Extract text from both uploaded files, then call generate_bid_no_bid_memo with tender_text and company_profile_text.

Public Tender Discovery

This project does not crawl the open internet. It searches explicit sources only.

connect_tender_source_urls
search_public_tenders

Use search_public_tenders for discovery leads only. Upload or connect the actual tender document before screening.

Data Files

Safe example files:

data/company-profile.example.json
data/sample-tender.md
data/historical-proposals.example.json

Private local files are ignored by git:

data/company-profile.local.json
data/current-tender.local.md
data/tender-sources.local.json

Example fallback is disabled by default. To demo with bundled example files:

MCP_ALLOW_EXAMPLE_FALLBACK=true npm run dev

On Windows PowerShell:

$env:MCP_ALLOW_EXAMPLE_FALLBACK="true"
npm run dev

Safety

The bid/no-bid memo is advisory only. Every output should be reviewed by tender, finance, legal, HSE, and management owners before submission.

Do not use this project to automatically submit tenders or make binding commercial decisions.

Development

npm run lint
npm run build
npm run eval

The eval suite runs through the real MCP stdio transport and checks tool exposure, safe failure behavior, screening outputs, and evidence traces.

Docs

• Architecture

• Demo transcript

• Evals

CI

GitHub Actions runs:

npm ci
npm run lint
npm run build
npm run eval

License

MIT