Last indexed: 22 May 2026 (590996)

Code and Nomenclature Tools

This page documents the nine code and nomenclature tools exposed by simap-mcp. These tools enable lookup and navigation of classification systems used by SIMAP.ch to categorize public procurement tenders, plus retrieval of Swiss canton codes for filtering.

These tools follow the standard tool contract: Zod schema validation, handler functions returning { content: [...] }, and registration via server.tool(). For broader tool architecture patterns, see page 3.2. For the SimapClient singleton that handles HTTP requests, see page 3.3.

Code Systems

SIMAP.ch uses four nomenclature systems. Each system has a dedicated pair of tools.

System	Full Name	Domain	Code Format
CPV	Common Procurement Vocabulary	EU-wide procurement categories	8 digits (e.g. `72000000`)
BKP	Baukostenplan	Swiss construction cost plan	Variable string (e.g. `211`)
NPK	Normpositionen-Katalog	Standardised construction positions	Variable string
OAG	Objektartengliederung	Object-type classification	Variable string

CPV codes are the most broadly useful — they can be passed directly to search_tenders via the cpvCodes filter parameter. BKP codes can be passed via the bkpCodes parameter. NPK and OAG codes are used for classification reference.

Sources: src/tools/codes/browse-cpv-tree.ts19-23 src/tools/codes/search-bkp-codes.ts19-22 src/tools/codes/search-npk-codes.ts19-22 src/tools/codes/search-oag-codes.ts19-22 src/tools/codes/browse-bkp-tree.ts19-23 src/tools/codes/browse-npk-tree.ts19-23 src/tools/codes/browse-oag-tree.ts19-23

Tool Pairs: `search_` and `browse__tree`

Each code system exposes exactly two tools, following the same two-pattern contract. The ninth tool, list_cantons, stands alone.

Tool registration flow — function imports to MCP tool names:

Title: Nomenclature Tool Registration Hierarchy

Sources: src/tools/codes/search-bkp-codes.ts77-84 src/tools/codes/search-cpv-codes.ts93-100 src/tools/codes/search-npk-codes.ts77-84 src/tools/codes/search-oag-codes.ts77-84 src/tools/codes/list-cantons.ts97-104 src/tools/codes/browse-bkp-tree.ts96-103 src/tools/codes/browse-npk-tree.ts95-102 src/tools/codes/browse-oag-tree.ts95-102 src/tools/codes/browse-cpv-tree.ts98-105

`search_*` Pattern

The search tools accept a free-text or numeric query and return a flat list of matching codes with their labels. They call the /search variant of the upstream endpoint.

Parameters (all four search_* tools share this schema):

Parameter	Type	Required	Description
`query`	string (min 1 char)	Yes	Keyword or code prefix
`lang`	`"de"` \| `"fr"` \| `"it"` \| `"en"`	No (default `"en"`)	Display language for labels

Schema definition example:

The query parameter is passed to the API as-is via the params object in simap.get(). CPV search results are flattened recursively before being returned to the user using the flattenCodes function src/tools/codes/search-cpv-codes.ts30-38 The output uses formatInlineCode to safely display the user's query in Markdown src/tools/codes/search-cpv-codes.ts69

Sources: src/tools/codes/search-bkp-codes.ts19-22 src/tools/codes/search-cpv-codes.ts19-22 src/tools/codes/search-cpv-codes.ts30-38 src/tools/codes/search-cpv-codes.ts47-53 src/tools/codes/search-npk-codes.ts19-22 src/tools/codes/search-oag-codes.ts19-22 src/tools/codes/search-cpv-codes.ts69

`browse_*_tree` Pattern

The browse tools navigate the code hierarchy level by level. When parentCode is omitted, they return the root categories. When provided, they return the direct children of that code. Entries that have further children are marked with 📂 in the formatted output.

Parameters (all four browse_*_tree tools share this schema):

Parameter	Type	Required	Description
`parentCode`	string	No	Code whose children to list. Omit for root level.
`lang`	`"de"` \| `"fr"` \| `"it"` \| `"en"`	No (default `"en"`)	Display language for labels

Schema definition example (CPV with validation):

Code-specific constraints:

CPV: parentCode must match /^[0-9]{8}$/ — exactly 8 digits src/tools/codes/browse-cpv-tree.ts19-23

BKP: parentCode must match /^[0-9]{1,3}(\.[0-9])?$/ src/tools/codes/browse-bkp-tree.ts19-23

NPK/OAG: parentCode must match /^[0-9]{1,10}$/ src/tools/codes/browse-npk-tree.ts19-23 src/tools/codes/browse-oag-tree.ts19-23

Hierarchy traversal pattern — user intent to API calls:

Title: Tree Traversal Logic

The 📂 indicator is computed by checking whether the API response includes a non-empty nested codes array on each entry. This check is performed using the hasChildren utility function in BKP, NPK, and OAG tools src/tools/codes/browse-bkp-tree.ts33-35

Sources: src/tools/codes/browse-cpv-tree.ts40-86 src/tools/codes/browse-cpv-tree.ts78-79 src/tools/codes/browse-bkp-tree.ts33-35 src/tools/codes/browse-npk-tree.ts33-35 src/tools/codes/browse-oag-tree.ts33-35

API Endpoints

Each tool calls the SimapClient singleton (simap) with one of the ENDPOINTS constants.

Tool-to-endpoint mapping with TypeScript types:

Title: Mapping Tool Handlers to API Endpoints

For search_* tools, query and language are sent as query parameters src/tools/codes/search-cpv-codes.ts48-51 For browse_*_tree tools, parentCode (when present) is sent as a query parameter src/tools/codes/browse-cpv-tree.ts44-47

Sources: src/tools/codes/search-bkp-codes.ts34-40 src/tools/codes/search-cpv-codes.ts47-53 src/tools/codes/browse-cpv-tree.ts44-52 src/tools/codes/search-npk-codes.ts34-40 src/tools/codes/search-oag-codes.ts34-40 src/tools/codes/browse-bkp-tree.ts51 src/tools/codes/browse-npk-tree.ts51 src/tools/codes/browse-oag-tree.ts51

Multilingual Labels

All code entries returned by the SIMAP API carry multilingual labels. The getTranslation() utility selects the label for the requested language, with the following fallback chain:

requested language → de → fr → en → it

Type structure for multilingual labels:

Title: Translation Data Flow

Every tool handler calls getTranslation(item.label, lang) before formatting each entry into the output string src/tools/codes/search-cpv-codes.ts73

Sources: src/tools/codes/search-bkp-codes.ts57 src/tools/codes/search-cpv-codes.ts73 src/tools/codes/browse-cpv-tree.ts77 src/tools/codes/browse-bkp-tree.ts74 src/tools/codes/browse-npk-tree.ts74 src/tools/codes/browse-oag-tree.ts74

`list_cantons` Tool

The list_cantons tool retrieves all Swiss canton codes and names. This tool takes no parameters src/tools/codes/list-cantons.ts17

API endpoint: The tool calls ENDPOINTS.CANTONS (/cantons/v1) via simap.get src/tools/codes/list-cantons.ts58

Name mapping: The tool includes a hardcoded CANTON_NAMES mapping to display full canton names in the output as the API only returns codes src/tools/codes/list-cantons.ts24-51

Canton codes data flow — API to formatted output:

Title: Canton List Data Flow

Sources: src/tools/codes/list-cantons.ts24-51 src/tools/codes/list-cantons.ts58-85

Tool File Reference

MCP Tool Name	Source File	Registration Function
`search_cpv_codes`	`src/tools/codes/search-cpv-codes.ts`	`registerSearchCpvCodes`
`browse_cpv_tree`	`src/tools/codes/browse-cpv-tree.ts`	`registerBrowseCpvTree`
`search_bkp_codes`	`src/tools/codes/search-bkp-codes.ts`	`registerSearchBkpCodes`
`browse_bkp_tree`	`src/tools/codes/browse-bkp-tree.ts`	`registerBrowseBkpTree`
`search_npk_codes`	`src/tools/codes/search-npk-codes.ts`	`registerSearchNpkCodes`
`browse_npk_tree`	`src/tools/codes/browse-npk-tree.ts`	`registerBrowseNpkTree`
`search_oag_codes`	`src/tools/codes/search-oag-codes.ts`	`registerSearchOagCodes`
`browse_oag_tree`	`src/tools/codes/browse-oag-tree.ts`	`registerBrowseOagTree`
`list_cantons`	`src/tools/codes/list-cantons.ts`	`registerListCantons`

Refresh this wiki

URL: https://deepwiki.com/Digilac/simap-mcp/4.2-code-and-nomenclature-tools