Tender Tools

Purpose and Scope

This page documents the three MCP tools that enable searching and retrieving tender information from SIMAP.ch. These tools provide the core functionality for discovering and examining Swiss public procurement opportunities.

The three tender tools are:

• search_tenders: Search and filter published tenders.
• get_tender_details: Retrieve complete details for a specific tender, with optional raw JSON output.
• get_publication_history: View the publication timeline of a project.

For documentation on nomenclature code tools (CPV, BKP, NPK, OAG), see Code and Nomenclature Tools. For organization-related tools, see Organization Tools.

Sources: , ,

---

Tool Architecture Overview

The tender tools follow a consistent implementation pattern within the MCP server architecture. Each tool is implemented as a standalone module that integrates with the server's tool registry.

Natural Language to Code Entity Mapping

This diagram bridges the gap between the tools as described in natural language and the specific code entities that implement them.

Title: Tender Tools Code Mapping

Tool Registration Pattern: Each tool exports a registration function (e.g., registerGetTenderDetails) that is called during server initialization. The registration function defines the tool name, description, schema, and handler. , , .

Validation Layer: All input parameters are validated using Zod schemas before processing. searchTendersInputShape and getTenderDetailsInputShape define the raw Zod shapes used for registration. , , .

API Communication: Tools delegate HTTP communication to the simap client instance, which uses the ENDPOINTS constants for URL construction. , .

Sources: , ,

---

search_tenders

Purpose

Searches public procurement tenders on SIMAP.ch with comprehensive filtering capabilities. This is the primary tool for discovering procurement opportunities.

Tool Name: search_tenders
Implementation:
API Endpoint: ENDPOINTS.PROJECT_SEARCH (/publications/v2/project/project-search)

Input Parameters

The tool accepts a variety of filters. If no filters are provided, the buildTenderSearchQuery function defaults the publicationFrom parameter to today's date in the Europe/Zurich timezone using zurichTodayDate(). , .

Parameter	Type	Required	Description
search	string	No	Search text (min 3 characters)
publicationFrom	string	No	Start date (YYYY-MM-DD)
publicationUntil	string	No	End date (YYYY-MM-DD)
projectSubTypes	array	No	Enum: construction, service, supply, etc.
cantons	array	No	Swiss canton codes (BE, VD, GE, ZH, etc.)
processTypes	array	No	Enum: open, selective, invitation, direct, no_process
pubTypes	array	No	Enum: tender, award_tender, correction, etc.
cpvCodes	array	No	8-digit CPV codes
bkpCodes	array	No	BKP construction codes (e.g., 211)
issuedByOrganizations	array	No	Organization UUIDs
lastItem	string	No	Pagination token (date|projectNumber)
lang	string	No	de, fr, it, en (default: en)

Pagination with lastItem

The SIMAP API uses a token-based pagination system. The search_tenders tool returns a lastItem token in its response if more results are available.

1. The initial search returns a list of projects.
2. If more results exist, the response text includes: More results available. Use lastItem: "[token]" to retrieve the next page.
3. To get the next page, call search_tenders again with the same filters, passing the lastItem value.

Query Building Logic

The buildTenderSearchQuery function maps user-facing parameter names to SIMAP API internal names using SEARCH_TENDERS_PARAM_MAP (e.g., cantons → orderAddressCantons). . It filters out empty arrays and ensures at least one filter is present. .

Sources: ,

---

get_tender_details

Purpose

Retrieves detailed information about a specific tender by combining data from project headers and publication details.

Tool Name: get_tender_details
Implementation:
API Endpoints:

• ENDPOINTS.PROJECT_HEADER(projectId)
• ENDPOINTS.PUBLICATION_DETAILS(projectId, publicationId)

Input Parameters

Parameter	Type	Required	Description
projectId	string	Yes	Project ID (UUID)
publicationId	string	Yes	Publication ID (UUID)
lang	string	No	Preferred language (de, fr, it, en)
fullRaw	boolean	No	(Added v1.2.0) Include complete unmodified API response as JSON

Implementation and Data Flow

Title: Tender Details Data Flow

The handler fetches the project header and publication details in parallel using Promise.all. . It uses a fetchOrNull helper to gracefully handle 404 errors from the API, throwing other errors using SimapApiError. .

v1.2.0 Update: The fullRaw parameter allows bypassing the standard formatting to see the entire JSON payload returned by the SIMAP API, which is appended to the Markdown output within a JSON code block. .

Sources: ,

---

get_publication_history

Purpose

Retrieves the publication history for a project, allowing users to track corrections, awards, and other related publications.

Tool Name: get_publication_history
Implementation:
API Endpoint: ENDPOINTS.PAST_PUBLICATIONS(publicationId)

Input Parameters

Parameter	Type	Required	Description
publicationId	string	Yes	Current publication ID (UUID)
lotId	string	No	Optional Lot ID to filter by lot

Response and Error Handling

• Success: Returns a list of past publications with dates, types, and SIMAP URLs constructed from SIMAP_API_BASE.
• No History: If the API returns a 400 error, the tool interprets this as the first publication in a project's history and returns a user-friendly message instead of failing.
• Formatting: Uses an internal getPubTypeLabel helper to convert technical pubType codes into human-readable English labels (e.g., award_tender -> "Award").

Sources: