Organization Tools

This page documents the organization-related MCP tools exposed by simap-mcp: list_institutions and search_proc_offices. These tools query Swiss public-sector entities (Confederation, cantons, and municipalities) that publish procurement tenders. They provide institution UUIDs and procurement office identifiers for use as filter values in the search_tenders tool.

Scope Note: While get_publication_history is physically located in src/tools/organizations/ src/tools/organizations/index.ts7 it is functionally part of the tender workflow and documented in page 4.1. The list_cantons tool is documented in page 4.2.

Sources: src/tools/organizations/list-institutions.ts1-4 src/tools/organizations/search-proc-offices.ts1-4

---

Overview

Organization tools are implemented in src/tools/organizations/ and registered via registerOrganizationTools(). They follow the project's standard tool pattern: Zod schema validation, API execution via the simap client, and Markdown formatting of results.

Registration Chain: Code Entity Mapping

Sources: src/tools/organizations/list-institutions.ts129-136 src/tools/organizations/search-proc-offices.ts137-144 src/tools/organizations/index.ts13-20

---

Tool-to-Endpoint Mapping

Both tools utilize the simap singleton instance of SimapClient to execute HTTP GET requests against specific SIMAP API endpoints defined in src/api/endpoints.ts.

API Request Flow: Code Entities

Tool Function	Endpoint Constant	API Path
registerListInstitutions()	ENDPOINTS.INSTITUTIONS	/institutions/v1/institutions
registerSearchProcOffices()	ENDPOINTS.PROC_OFFICES	/procoffices/v1/po/public

Sources: src/tools/organizations/list-institutions.ts59-61 src/tools/organizations/search-proc-offices.ts83-86

---

list_institutions

File: src/tools/organizations/list-institutions.ts src/tools/organizations/list-institutions.ts1-4
MCP tool name: list_institutions

Purpose

Returns a list of Swiss public institutions. The tool fetches the complete list of institutions from the API and performs client-side filtering if a search term is provided. The resulting IDs are used as filters in search_tenders (issuedByOrganizations) or search_proc_offices (institutionId).

Input Schema

The schema listInstitutionsInputShape src/tools/organizations/list-institutions.ts19-27 validates:

Parameter	Type	Required	Validation	Description
search	string	No	.min(3), .max(500)	Filter by name (case-insensitive, matches any language).
lang	enum	No	de, fr, it, en	Language for names. Defaults to en.

Implementation Details

The tool retrieves the full InstitutionsResponse using InstitutionsResponseSchema src/tools/organizations/list-institutions.ts59-61 If a search string is provided, the matchesSearch helper src/tools/organizations/list-institutions.ts40-50 checks the search term against all available language translations (de, fr, it, en) for each institution. Results are capped at MAX_RESULTS = 50 src/tools/organizations/list-institutions.ts35

Request Processing Flow

Sources: src/tools/organizations/list-institutions.ts55-124 src/utils/translation.ts1-25 tests/tools/list-institutions.test.ts49-67

---

search_proc_offices

File: src/tools/organizations/search-proc-offices.ts src/tools/organizations/search-proc-offices.ts1-4
MCP tool name: search_proc_offices

Purpose

Searches for specific public procurement offices. Unlike list_institutions, this tool passes search parameters directly to the API endpoint as query parameters src/tools/organizations/search-proc-offices.ts75-86

Input Schema

The schema searchProcOfficesInputShape src/tools/organizations/search-proc-offices.ts18-30 requires at least one of the following:

Parameter	Type	Required	Validation	Description
search	string	No*	.min(3), .max(500)	Name of the office to search for.
institutionId	string	No*	.uuid()	Filter by parent institution UUID.

*At least one parameter must be provided src/tools/organizations/search-proc-offices.ts61-72

Implementation Details

The tool maps the API response ProcOfficeType to human-readable English labels (e.g., federal, cantonal, communal) via getTypeLabel() src/tools/organizations/search-proc-offices.ts43-53 Results include the Office ID, Type, Parent Institution ID, and Competence Centre ID src/tools/organizations/search-proc-offices.ts107-115 Results are limited to MAX_RESULTS = 50 src/tools/organizations/search-proc-offices.ts38

Sources: src/tools/organizations/search-proc-offices.ts58-132 tests/tools/search-proc-offices.test.ts66-77

---

Relationship and Workflow

The organization tools create a discovery hierarchy. Users typically find an institution first, then find its specific procurement offices or search for tenders directly.

Workflow: Organization Discovery to Tender Filtering

Typical Usage Pattern

1. Discover Institution: list_institutions(search: "Canton de Vaud") -> Returns ID uuid-123 src/tools/organizations/list-institutions.ts100-102
2. Discover Offices: search_proc_offices(institutionId: "uuid-123") -> Returns list of specific offices in Vaud src/tools/organizations/search-proc-offices.ts79-81
3. Filter Tenders: search_tenders(issuedByOrganizations: ["uuid-123"]) -> Returns all tenders published by that institution src/tools/organizations/list-institutions.ts113

Sources: src/tools/organizations/list-institutions.ts113 src/tools/organizations/search-proc-offices.ts121