ESG Hub MCP Server

Queue one ESG Hub page for human curation — delist, remove, or review — with a reason. Nothing changes immediately: the call records a pending request and returns a `proposal_id`; the page is not modified until a curator approves it. Use it when an article is outdated, duplicated, or inaccurate; to edit its facet tags instead use tag_content. `action` controls the requested outcome: `delist` hides the page from listings, `remove` deletes it, and `review` (the default) flags it for a curator to decide. Give `page_id` as a permalink, slug, or record ID (resolved server-side) and a `reason` of at least 10 characters. Requires ESG_HUB_WRITE_TOKEN; rate-limited.

Discover the filter vocabulary for the knowledge base: total counts plus the exact `section`, `pillar`, and source-`domain` values with their counts. Call it before list_esg_pages or list_esg_resources so filters match real values; for server version and health use get_server_info. It takes no parameters, returns a single object (never paginated), and the lists are seeded reference values that change only on deploy, so they can be cached within a session. Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Read one ESG Hub article in full, addressed by permalink (e.g., 'standards/gri-101'), bare slug, or record ID ('page:abc123'). Use it once search_esg, search_content, or list_esg_pages has returned an identifier; to fetch a page's neighbours rather than its content use get_related. Returns the complete article body plus section, pillar, keywords, and canonical URL. It resolves only `page` records — a resource URL returns NOT_FOUND — and a redirect-only record resolves to its target; an unknown identifier returns NOT_FOUND. Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Traverse the ESG Hub knowledge graph one hop from a page and return every connected record grouped by edge type. Use it after get_esg_page when you need neighbouring concepts; to read a page's own content use get_esg_page. Returns at most 15 related pages and, today, only `related_pages` edges; a page with no links returns an empty group list, not an error. There is no pagination. `record_id` accepts a `page:` record ID or a permalink; `edge_type` filters the result to one edge type (default: all). Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Use this first to confirm the ESG Hub MCP server is reachable and see its version and API base. It performs one liveness round-trip and returns only server metadata — name, version, API base, tool_count, and healthy — and never fails on an unreachable API: it returns healthy=false rather than an error. For sections, pillars, source domains, or totals use get_esg_metadata.

Look up one glossary term by record ID ('term:abc123'), permalink, or exact name and return its full definition and facets. Use it when the user asks 'what is <term>'; to find terms by topic, or across all content, use search_esg or search_content, and to survey the glossary use list_terms. Name matching is exact (case-insensitive) with no fuzzy or partial matching, and it returns a single term, never a list. The `definition` field is the authoritative text and `facets` carries the topic/content_type classification; an unknown identifier returns NOT_FOUND. Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Enumerate ESG Hub articles, optionally filtered by `section`, `pillar`, or a title substring (`query` — an exact substring, not fuzzy). Use it to browse a whole section; to find articles by meaning use search_content. Results are ordered by section then title and returned one page at a time: pass the response's `next_offset` back as `offset` until `has_more` is false. `section` and `pillar` values must be taken from get_esg_metadata, and `offset` is a raw row count so advance it by `limit`; `limit` caps at 100 (default 20). A filter that matches nothing, or an `offset` past the end, returns an empty item list with `has_more=false`. Cached ~5 minutes; rate-limited per IP; retry on 5xx.

Enumerate curated external ESG resources (standards bodies, regulators, tools, databases) with their source URLs, optionally filtered by exact source `domain` or a title substring (`query` — an exact substring, not fuzzy). Use it to assemble authoritative references; for ESG Hub's own articles use list_esg_pages. Results are ordered by title and paged: pass `next_offset` back as `offset`, advancing it by `limit` (a raw row count). `domain` must be a host from get_esg_metadata's domain list; `limit` caps at 100 (default 20). A filter that matches nothing, or an `offset` past the end, returns an empty item list with `has_more=false`. Cached ~5 minutes; rate-limited per IP; retry on 5xx.

Enumerate the ESG reporting frameworks and standards the knowledge base covers (GRI, SASB/ISSB, TCFD, ESRS, CDP, TNFD, …), with each framework's abbreviation, description, and official website. Use it to discover coverage; for the ESG Hub articles that explain a standard use list_esg_pages with section='standards'. Results are ordered by name and paged: pass `next_offset` back as `offset`, a raw row count so advance it by `limit`; `limit` defaults to 20 and is capped at 100. An `offset` past the end returns an empty `items` list with `has_more=false`. Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Return the ESG Hub industry taxonomy (IFRS/SASB-style): every industry with its stable `industry_id`, English/Chinese names, and the `sector_id` it belongs to. Use it to obtain valid industry values for tag_content or to group coverage by sector; for article sections and source domains use get_esg_metadata. It takes no parameters and returns the complete taxonomy in one response (no pagination). The taxonomy is seeded reference data, not derived from articles, so it is stable across sessions and cached ~10 minutes; rate-limited per IP; retry on 5xx.

Enumerate glossary terms, optionally filtered by an exact name substring (`query` — case-insensitive, not fuzzy). Use it to survey the glossary or page through terminology; to fetch one term's definition use get_term, and to search all content use search_esg or search_content. Results are ordered by name and paged: pass `next_offset` back as `offset` (a raw row count, so advance it by `limit`); `limit` defaults to 20 and is capped at 100. A query that matches nothing, or an `offset` past the end, returns an empty item list with `has_more=false`. Cached ~10 minutes; rate-limited per IP; retry on 5xx.

Submit a new glossary term for human review. Nothing is published immediately: the call creates a pending proposal and returns a `proposal_id`; a reviewer decides whether it goes live, and only an approved term later appears in get_term. Use it only when the user explicitly wants to contribute a term; to look one up use get_term. `name` is the display name and `definition` must be at least 10 characters; `facets` is optional and its values should come from get_esg_metadata / list_industries vocabularies. Requires a write token in ESG_HUB_WRITE_TOKEN — a missing or invalid token returns 401 — and calls are rate-limited.

Hybrid search that fuses 384-dim semantic similarity with BM25 and ESG re-ranking across ESG Hub articles and external resources. Use for conceptual or paraphrased questions — natural-language phrases work better than single tokens because `query` is embedded; when the user gives an exact identifier or phrase prefer the cheaper search_esg. `query` must be non-empty and `limit` defaults to 10 and is capped at 50. Returns one ranked page of up to `limit` items, each carrying a fused relevance score (higher is better); there is no pagination, so raise `limit` to widen, and unlike search_esg there is no `source` filter. Zero matches returns an empty item list, not an error. Cached ~2 minutes; rate-limited per IP; retry on 5xx.

Exact keyword (BM25) search across ESG Hub articles and curated external resources. Use when the user supplies a specific term, identifier, or phrase (e.g., 'GRI 305', 'Scope 3'); for paraphrased or conceptual questions prefer search_content, which adds semantic similarity. Terms are matched individually, not as one exact phrase, and `source` narrows to 'pages' (ESG Hub articles) or 'external' (curated third-party URLs). Returns one ranked page of up to `limit` (max 50) items — there is no pagination, so raise `limit` to widen; zero matches returns an empty item list, not an error. Reads are cached ~2 minutes and rate-limited per IP; a 5xx means the API is redeploying — retry shortly.

Replace the facet tags on one existing ESG Hub page: `topic`, `industry`, `framework`, `jurisdiction`, `stakeholder`, and `content_type`. The supplied `facets` object replaces the page's facet set, so any facet key you omit is cleared; the page body and title are never changed or deleted. The response echoes the page's new `facets` and `updated_at`. The array facets (`topic`, `industry`, `framework`, `jurisdiction`, `stakeholder`) each accept multiple values, while `content_type` is a single string; values are validated against the vocabulary from get_esg_metadata / list_industries, and an unrecognised value or key is rejected with 400. Give `page_id` as a permalink, slug, or record ID — permalinks are resolved to the underlying record server-side. Use it to curate tags; to read a page use get_esg_page, and to queue a removal use flag_content. Requires ESG_HUB_WRITE_TOKEN; rate-limited.