# ESG Hub

<!-- mcp-name: com.ascent-partners/esg-hub -->

> **An open-access encyclopedia of Environmental, Social, and Governance (ESG) knowledge by [Ascent Partners Foundation](https://www.ascent.partners)** — 350+ articles, 240+ curated resources, books, courses, AI search, a public REST API, and an MCP server. Available in English, Simplified Chinese, and Traditional Chinese (Hong Kong).

[![CI](https://github.com/simonmak-ascent/esg-hub/actions/workflows/ci.yml/badge.svg)](https://github.com/simonmak-ascent/esg-hub/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-com.ascent-partners%2Fesg-hub-4CAF50)](https://registry.modelcontextprotocol.io/v0/servers?search=com.ascent-partners/esg-hub)
[![Glama](https://glama.ai/mcp/connectors/com.ascent-partners/esg-hub/badges/score.svg)](https://glama.ai/mcp/connectors/com.ascent-partners/esg-hub)
[![License: MIT (code)](https://img.shields.io/badge/code-MIT-yellow.svg)](LICENSE)
[![Content: CC BY-SA 4.0](https://img.shields.io/badge/content-CC%20BY--SA%204.0-blue.svg)](https://creativecommons.org/licenses/by-sa/4.0/)

**Live site:** [esg-hub.ascent.partners](https://esg-hub.ascent.partners)

## Overview

- **Knowledge base** — 350+ ESG articles across standards (GRI, IFRS S1/S2, TCFD, TNFD, ESRS), regulations, frameworks, ratings, and regional (HK/APAC) guidance
- **AI search** — ask questions in natural language; answers grounded in the knowledge base (SurrealDB BM25 + vector search, DeepSeek, Brave Search across authoritative ESG domains)
- **Public REST API** — open access to all content: [`/api/v1`](https://esg-hub.ascent.partners/api/v1)
- **MCP server** — connect AI agents directly: [`@esg-hub/mcp-server`](mcp-server/)
- **Learning resources** — free courses, books, and a curated video library
- **i18n** — English, Simplified Chinese (zh), Traditional Chinese — Hong Kong (hk)

## Architecture

```mermaid
flowchart TB
  U["User / AI agent"] --> WEB["Next.js 16 App Router · React 19<br/>next-intl (en / zh / hk)"]
  WEB --> DB[("SurrealDB Cloud<br/>BM25 + vector search")]
  WEB --> AI["DeepSeek + Brave Search<br/>grounded answers"]
  WEB --> API["Public REST API · /api/v1"]
  API --> MCP["MCP server<br/>@simonmak-ascent/esg-hub-mcp"]
  V["APG ALB · esg-hub.ascent-partners.com"] --> WEB
```

## How a query is answered

```mermaid
sequenceDiagram
  autonumber
  actor U as User
  participant W as Next.js app (App Router)
  participant API as /api/ai-search · /api/ai-chat
  participant S as search.ts
  participant DB as SurrealDB (page · section · embedding)
  participant AI as DeepSeek
  participant X as Brave / OpenAlex
  U->>W: ask a question
  W->>API: POST query (+ locale)
  API->>S: search(query)
  S->>DB: BM25 keyword + vector (embedding) hybrid ranking
  DB-->>S: ranked pages / sections + citations
  API->>AI: synthesize answer from ranked context
  API->>X: enrich (web + research)
  X-->>API: references
  API-->>W: streamed answer + citations
  W-->>U: grounded response
```

## Data model

```mermaid
erDiagram
  PAGE ||--o{ SECTION : contains
  SECTION ||--o{ EMBEDDING : "vectorised as"
  FRAMEWORK ||--o{ PAGE : classifies
  INDUSTRY ||--o{ PAGE : tags
  TERM ||--o{ PAGE : defines
  PAGE {
    string id
    string slug
    string title
    string lang
  }
  SECTION {
    string id
    string heading
    text body
  }
  EMBEDDING {
    vector vector
    string model
  }
```

`FRAMEWORK`, `INDUSTRY` and `TERM` are the facets exposed by the `/api/v1/*` REST
resources; `page`, `section` and `embedding` are the core SurrealDB tables.

## Deployment

Production runs on the ecs-01/02/03 HA fleet as the digest-pinned container declared in
`container.json` — the image is the deployable, not a release tree on a node. The fleet runs it as
a container on `:3210`, and no node runs a routing web server. The ALB terminates TLS and routes
`esg-hub.ascent.partners` to the container's port. The former Vercel project was retired. See
`apg-infra` for the fleet deployment.

```mermaid
flowchart LR
  DEV["git push / PR"] --> CI["GitHub Actions<br/>lint · test · e2e · health-check"]
  CI -->|merge to main| IMG["digest-pinned image<br/>container.json"]
  IMG -->|the image is the deployable| PROD["container · :3210"]
  ALB["APG ALB · TLS termination"] -->|esg-hub.ascent.partners| PROD
  PROD --> SURF["/api/mcp · /api/v1<br/>MCP + REST surfaces"]
```

## Tech Stack

Next.js 16 (App Router, React 19) · SurrealDB Cloud · Tailwind CSS v4 · next-intl · Vitest + Playwright · APG fleet (containerised)

## Quick Start (≤ 5 minutes)

**Fastest path — nothing to install:** use the live site and the open API.

- **Site:** <https://esg-hub.ascent.partners>
- **API (no auth):** `GET https://esg-hub.ascent.partners/api/v1/pages`

Run a local copy:

```bash
git clone https://github.com/simonmak-ascent/esg-hub.git
cd esg-hub
pnpm install        # note: requires sibling repo ../tool_package (private)
cp .env.example .env  # fill in your own values
pnpm dev
```

Useful commands: `pnpm lint` · `npx tsc --noEmit` · `npx vitest run` · `pnpm verify:db`

> **Note:** the app renders content from a SurrealDB database — you need your own instance and content to run a full copy. The public site and API are freely accessible without running anything.

## API & MCP

- **REST API:** open, no auth — `GET /api/v1/pages`, `/api/v1/search?q=...`, `/api/v1/resources`, `/api/v1/meta` ([docs](https://esg-hub.ascent.partners/en/developers/api))
- **MCP server:** see [`mcp-server/`](mcp-server/) — gives AI agents tools to search and read the knowledge base

## Contributing

- **Content errors** (wrong/outdated info, dead links): open a [content error issue](https://github.com/simonmak-ascent/esg-hub/issues/new/choose)
- **Bugs and code changes**: see [CONTRIBUTING.md](CONTRIBUTING.md)
- **Security vulnerabilities**: report privately via [SECURITY.md](SECURITY.md)

## Use with Context7

Up-to-date ESG Hub documentation is indexed on [Context7](https://context7.com/simonmak-ascent/esg-hub), so coding agents can pull it into context on demand. With the Context7 MCP server or `ctx7` CLI installed, name the library in your prompt:

```text
use library /simonmak-ascent/esg-hub for API and docs
```

## License

- **Code:** [MIT](LICENSE)
- **Encyclopedia content:** [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) by Ascent Partners Foundation

---

An [Ascent Partners Foundation](https://www.ascent.partners) project.

If this saves you time, a ⭐ on GitHub helps others find it.