mcp-statdb 1.3.2

package/License

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,351 @@
+# CNBS MCP Server
+
+MCP server for querying China National Bureau of Statistics (NBS) data and major international statistical databases. All data is fetched from real APIs — no mock data.
+
+## Data Sources
+
+| Source | Auth | Coverage |
+|--------|------|----------|
+| **China NBS** (data.stats.gov.cn) | None | Monthly / Quarterly / Yearly / Provincial domestic data |
+| **World Bank** (api.worldbank.org) | None | 200+ countries — GDP, CPI, trade, population, FDI, Gini, etc. |
+| **IMF DataMapper** | None | WEO forecasts — GDP growth, inflation, government debt, current account |
+| **OECD SDMX** | None | Member-country quarterly GDP, employment, leading indicators |
+| **BIS Statistics** | None | Effective exchange rates, credit gaps, property prices, cross-border banking |
+| **FRED** (Federal Reserve) | `X-Fred-Api-Key` request header | US rates, CNY/USD, oil, gold, S&P 500, M2 |
+| **NBS Census** | None | Population (2020), Economic (2018), Agriculture (2016) censuses |
+| **NBS Departments** | None | Finance, Industry, Trade, Agriculture, PBoC monetary, Social Security, Housing, Energy |
+
+> **FRED API Key:** Free registration at https://fred.stlouisfed.org/docs/api/api_key.html  
+> Pass it as the `X-Fred-Api-Key` request header (HTTP mode) or set `FRED_API_KEY` env var (stdio mode).
+
+---
+
+## Installation
+
+### npx (Recommended)
+
+```bash
+npx mcp-cnbs
+```
+
+### HTTP transport
+
+```bash
+npx mcp-cnbs --port 12345
+```
+
+### Install globally
+
+```bash
+npm install -g mcp-cnbs
+mcp-cnbs
+```
+
+---
+
+## MCP Client Configuration
+
+### stdio mode (npx)
+
+**Supported clients:** Claude Desktop, Cursor, Windsurf, Cherry Studio, Trae, Continue, and all MCP-compatible clients.
+
+```json
+{
+  "mcpServers": {
+    "cnbs": {
+      "command": "npx",
+      "args": ["mcp-cnbs"]
+    }
+  }
+}
+```
+
+With FRED support:
+
+```json
+{
+  "mcpServers": {
+    "cnbs": {
+      "command": "npx",
+      "args": ["mcp-cnbs"],
+      "env": {
+        "FRED_API_KEY": "your_fred_api_key"
+      }
+    }
+  }
+}
+```
+
+### HTTP mode (remote)
+
+**Supported clients:** Trae, Cherry Studio, and other clients with HTTP transport support.
+
+**Free demo on ModelScope (no FRED):**
+```json
+{
+  "mcpServers": {
+    "cnbs": {
+      "url": "https://mcp.api-inference.modelscope.net/c2ca6ece4e9946/mcp"
+    }
+  }
+}
+```
+
+**HTTP mode with FRED:**
+```json
+{
+  "mcpServers": {
+    "cnbs": {
+      "url": "https://your-cnbs-server/mcp",
+      "headers": {
+        "X-Fred-Api-Key": "your_fred_api_key"
+      }
+    }
+  }
+}
+```
+
+> Free public demo by Alibaba Cloud ModelScope. No auth required.  
+> For production use, [deploy your own instance](https://modelscope.cn/mcp/servers/thatcoder/cnbs).
+
+---
+
+## HTTP Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` or `/mcp` | POST | Streamable HTTP — initialize session or send requests |
+| `/` or `/mcp` | GET | SSE notification stream (requires `Mcp-Session-Id` header) |
+| `/` or `/mcp` | DELETE | Terminate session (requires `Mcp-Session-Id` header) |
+| `/sse` | GET | Legacy SSE mode |
+| `/message` | POST | Legacy SSE messages |
+
+---
+
+## Tools
+
+### NBS Core Query
+
+| Tool | Description |
+|------|-------------|
+| `cnbs_search` | Search by keyword, returns latest value — **start here** |
+| `cnbs_batch_search` | Batch search multiple keywords in one call |
+| `cnbs_economic_snapshot` | One-shot snapshot of 10 key Chinese macro indicators (GDP, CPI, PPI, PMI, unemployment, industrial output, retail sales, fixed investment, trade, M2) |
+| `cnbs_compare` | Compare data across regions or time periods |
+| `cnbs_fetch_nodes` | Get category tree nodes — accepts one or multiple categories |
+| `cnbs_fetch_metrics` | Get indicator list — accepts one or multiple `setIds` |
+| `cnbs_fetch_series` | Get time series data |
+| `cnbs_fetch_end_nodes` | Recursively get all leaf nodes |
+
+### NBS Reference
+
+| Tool | Description |
+|------|-------------|
+| `cnbs_get_guide` | Full tool guide (useful for LLMs to self-orient) |
+| `cnbs_get_regions` | Region codes and names (GB/T 2260) |
+| `cnbs_get_categories` | NBS category codes |
+| `cnbs_list_data_sources` | All available data sources with tool mappings |
+| `cnbs_fetch_data_from_source` | Fetch data from any named source |
+| `cnbs_get_source_categories` | Categories for a given source |
+| `cnbs_search_in_source` | Search within a specific source |
+
+### World Bank
+
+| Tool | Description |
+|------|-------------|
+| `ext_world_bank` | Query a single indicator across countries and years |
+| `ext_world_bank_multi` | Query multiple indicators at once |
+| `ext_world_bank_indicators` | List all supported World Bank indicators |
+
+### IMF
+
+| Tool | Description |
+|------|-------------|
+| `ext_imf` | Query IMF WEO data — accepts one or multiple indicators |
+| `ext_imf_indicators` | List supported IMF indicators |
+| `ext_imf_all_indicators` | Full IMF DataMapper indicator catalog |
+
+### OECD
+
+| Tool | Description |
+|------|-------------|
+| `ext_oecd` | Query OECD SDMX data by dataset and key |
+| `ext_oecd_datasets` | List supported OECD datasets |
+
+### BIS
+
+| Tool | Description |
+|------|-------------|
+| `ext_bis` | Query BIS statistics — accepts one or multiple countries |
+| `ext_bis_datasets` | List supported BIS datasets with key templates |
+
+### FRED (Federal Reserve)
+
+| Tool | Description |
+|------|-------------|
+| `ext_fred` | Query FRED series — accepts one or multiple series |
+| `ext_fred_series` | List all supported FRED series |
+
+### China Extended Sources
+
+| Tool | Description |
+|------|-------------|
+| `ext_cn_census` | NBS census data (population, economic, agriculture) |
+| `ext_cn_department` | NBS department statistics by ministry |
+| `ext_cn_department_list` | All department categories and indicator keywords |
+
+### Cross-Source Comparison
+
+| Tool | Description |
+|------|-------------|
+| `ext_global_compare` | Simultaneously query World Bank + IMF for the same indicator across countries |
+
+---
+
+## Quick Examples
+
+### China Economy At a Glance
+
+```
+// Full macro snapshot in one call
+cnbs_economic_snapshot()
+
+// Latest single indicator
+cnbs_search(keyword="GDP")
+
+// Batch indicators
+cnbs_batch_search(keywords=["GDP", "CPI", "城镇化率", "出生率"])
+
+// Regional comparison
+cnbs_compare(keyword="GDP", regions=["北京", "上海", "广东"], compareType="region")
+
+// Time series
+cnbs_fetch_series(setId="...", metricIds=["..."], periods=["2015YY-2024YY"])
+```
+
+### International Comparison
+
+```
+// China GDP growth vs peers (World Bank)
+ext_world_bank(indicator="GDP_GROWTH", countries=["CHN","USA","DEU","JPN","IND"], startYear=2015)
+
+// Multiple indicators for China
+ext_world_bank_multi(indicators=["GDP_GROWTH","CPI","UNEMPLOYMENT"], countries=["CHN"], startYear=2010)
+
+// IMF: single indicator
+ext_imf(indicators="GDP_GROWTH", countries=["CHN","USA","JPN"], periods=["2022","2023","2024","2025"])
+
+// IMF: multiple indicators in one call
+ext_imf(indicators=["GDP_GROWTH","CPI_INFLATION","GOVT_DEBT"], countries=["CHN","USA"], periods=["2020","2021","2022","2023","2024"])
+
+// World Bank + IMF side-by-side
+ext_global_compare(wbIndicator="GDP_GROWTH", imfIndicator="GDP_GROWTH", countries=["CHN","USA","DEU","JPN"])
+```
+
+### BIS & FRED
+
+```
+// BIS: single country
+ext_bis(dataset="EER", countries="CN", lastNObservations=36)
+
+// BIS: multiple countries in one call
+ext_bis(dataset="EER", countries=["CN","US","DE","JP"], lastNObservations=24)
+
+// BIS: credit gap
+ext_bis(dataset="CREDIT_GAP", countries=["CN","US"], lastNObservations=20)
+
+// FRED: single series
+ext_fred(series="OIL_PRICE_WTI", limit=100, sortOrder="desc")
+
+// FRED: multiple series in one call
+ext_fred(series=["FED_FUNDS","CNY_USD","OIL_PRICE_WTI","GOLD_PRICE"], limit=30, sortOrder="desc")
+```
+
+### NBS Census & Departments
+
+```
+// 2020 Population census
+ext_cn_census(type="population")
+
+// PBoC M2 monetary data
+ext_cn_department(department="monetary", indicator="M2货币供应量")
+
+// All finance ministry indicators
+ext_cn_department(department="finance", fetchAll=true)
+```
+
+---
+
+## NBS Category Codes
+
+| Code | Category | Typical Indicators |
+|------|----------|--------------------|
+| 1 | Monthly | CPI, PPI, Industrial Output, PMI |
+| 2 | Quarterly | GDP quarterly growth |
+| 3 | Annual | GDP, population, urbanization rate |
+| 5 | Provincial Quarterly | Provincial GDP by quarter |
+| 6 | Provincial Annual | Provincial GDP, population by year |
+| 7 | Other / Surveys | Household surveys, special surveys |
+
+## NBS Time Format
+
+- Annual: `2024YY`, range `["2020YY-2024YY"]`
+- Quarterly: `2024A/B/C/D` (A=Q1, B=Q2, C=Q3, D=Q4), shortcuts `LAST6/LAST12/LAST18`
+- Monthly: `202401MM`, range `["202301MM-202412MM"]`
+
+## NBS Region Codes
+
+Follows GB/T 2260 standard. Use `cnbs_get_regions` for the full list.
+
+| Region | Code |
+|--------|------|
+| National | `000000000000` |
+| Beijing | `110000000000` |
+| Shanghai | `310000000000` |
+| Guangdong | `440000000000` |
+| Zhejiang | `330000000000` |
+| Jiangsu | `320000000000` |
+
+---
+
+## Authentication
+
+No authentication required by default. Enable Bearer token auth:
+
+### stdio / HTTP mode
+
+```bash
+npx mcp-cnbs --port 12345 --auth-token your-secret-token
+# or via env var
+MCP_CNBS_AUTH_TOKEN=your-secret-token npx mcp-cnbs --port 12345
+```
+
+Requests must then include:
+```
+Authorization: Bearer your-secret-token
+```
+
+### Cloudflare Workers
+
+```bash
+npx wrangler secret put MCP_CNBS_AUTH_TOKEN
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run start
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Network access to `data.stats.gov.cn`, `api.worldbank.org`, `www.imf.org`, `sdmx.oecd.org`, `stats.bis.org`, `api.stlouisfed.org`
+
+## License
+
+MIT