webmcp-nexus-core 0.1.9 → 0.1.10

package/README.en.md

@@ -0,0 +1,178 @@
+<div align="center">
+
+# webmcp-nexus-core
+
+**The build-time core of WebMCP Nexus — a `ts-morph`-powered engine for TypeScript type extraction and JSON Schema generation.**
+
+[![npm version](https://img.shields.io/npm/v/webmcp-nexus-core.svg)](https://www.npmjs.com/package/webmcp-nexus-core)
+[![npm downloads](https://img.shields.io/npm/dm/webmcp-nexus-core.svg)](https://www.npmjs.com/package/webmcp-nexus-core)
+[![license](https://img.shields.io/npm/l/webmcp-nexus-core.svg)](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE)
+
+[简体中文](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/README.md) | English
+
+</div>
+
+---
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Features](#features)
+- [Why Use It](#why-use-it)
+- [Installation](#installation)
+- [Usage](#usage)
+- [API Overview](#api-overview)
+- [Ecosystem](#ecosystem)
+- [Links](#links)
+- [License](#license)
+
+## Introduction
+
+`webmcp-nexus-core` is the **build-time core** of the [WebMCP Nexus](https://github.com/alibaba/webmcp-nexus) toolchain. It is responsible for:
+
+1. Statically analysing source code via [`ts-morph`](https://ts-morph.com/) to find functions intended as WebMCP tools;
+2. Inferring [JSON Schema](https://json-schema.org/)-compliant tool descriptions from each function's **TypeScript types and JSDoc**;
+3. Generating injection code that attaches a `__webmcpSchema` field to each tool function — at runtime the SDK reads that field and registers the tools with `navigator.modelContext`.
+
+This package is **not intended to be consumed directly by application authors**. It is the shared engine behind [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus) and [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus). If you are building a **custom build-tool integration** (Rspack, Rollup, esbuild, …) you can reuse this package directly.
+
+## Features
+
+- 🔬 **`ts-morph`-driven static type analysis** — function signature *is* the JSON Schema; one source of truth.
+- 🪶 **Zero runtime overhead** — schemas are generated at build time; no reflection or parsing at runtime.
+- 📦 **Bundler-agnostic and reusable** — exposes a pure functional `transformCode(code, filePath, options?)` interface.
+- 🔁 **Reverse tracing** — traces back from `registerGlobalTools` / `useWebMcpTools` call sites to the function definitions; tool functions themselves require no markers.
+- 🧩 **Rich TypeScript support** — primitives, literal unions (→ `enum`), optional properties, nested objects (recursion ≤ 3 levels), and more.
+- 🛠️ **Alias resolution** — handles `import * as api from '@alias/xxx'` style module specifiers (compatible with webpack `$` exact-match syntax).
+
+## Why Use It
+
+| Dimension              | Common practice                                | webmcp-nexus-core                                                  |
+| ---------------------- | ---------------------------------------------- | ------------------------------------------------------------------ |
+| Schema source          | Hand-written JSON Schema + TS types in sync   | **Inferred from TS types automatically** — one source of truth    |
+| Runtime cost           | Decorators / reflection / wrappers            | **Zero runtime cost** — all schemas are injected at build time    |
+| Bundler coupling       | Tightly coupled to a specific bundler         | **Bundler-agnostic** — pure-functional core, reusable across tools |
+| Type drift             | Manual sync between TS types and JSON Schema  | TS types are authoritative; the editor catches drift in real time |
+
+## Installation
+
+```bash
+# pnpm (recommended)
+pnpm add webmcp-nexus-core
+
+# npm
+npm install webmcp-nexus-core
+
+# yarn
+yarn add webmcp-nexus-core
+```
+
+> Most users **don't** need to install this package directly; it is pulled in automatically as a dependency of [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus) and [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus).
+
+## Usage
+
+### Calling from a custom build tool
+
+> **Important**: `transformCode` only processes source files that **contain a `registerGlobalTools` / `useWebMcpTools` call** — it traces back from those calls to the tool function definitions. The injected code is inserted before the first registration call, not into the tool function's own file.
+
+```ts
+import { transformCode } from 'webmcp-nexus-core';
+
+// Example: contents of an entry file like src/main.ts
+const code = `
+import { registerGlobalTools } from 'webmcp-nexus-sdk';
+import * as queries from './tools/queries';
+
+registerGlobalTools(queries);
+`;
+
+const result = transformCode(code, '/abs/path/to/project/src/main.ts', {
+  projectRoot: '/abs/path/to/project',
+  alias: { '@': '/abs/path/to/project/src' },
+});
+
+if (result.transformed) {
+  // result.code now has __webmcpSchema injected for each queries.* tool, before the registerGlobalTools call
+  console.log(result.code);
+}
+```
+
+Sample injection output (from [`generateSchemaInjectionCode`](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/src/schema-generator.ts)):
+
+```ts
+import { registerGlobalTools } from 'webmcp-nexus-sdk';
+import * as queries from './tools/queries';
+
+// [webmcp-nexus-core] build-time injected schema metadata
+queries.searchTasks.__webmcpSchema = {
+  "description": "Search tasks by keyword.",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "Search keyword" },
+      "limit": { "type": "number", "description": "Maximum number of results (default 50)" }
+    },
+    "required": ["query"]
+  },
+  "readOnly": true
+};
+
+registerGlobalTools(queries);
+```
+
+> The injected schema contains only three fields: `description`, `inputSchema`, and `readOnly`. At runtime, [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) reads it and translates it into the format expected by `navigator.modelContext.registerTool()` (e.g. `readOnly` → `annotations.readOnlyHint`).
+
+## API Overview
+
+```ts
+// High-level API: extract + inject in one call
+export function transformCode(
+  code: string,
+  filePath: string,
+  options?: TransformOptions
+): TransformResult;
+
+// Low-level API (advanced users)
+export function extractToolsFromFile(
+  fileContent: string,
+  filePath: string,
+  projectRoot?: string,
+  alias?: AliasMap
+): ExtractionResult | null;
+
+export function generateSchema(
+  properties: PropertyInfo[],
+  description?: string
+): JsonSchema;
+
+export function generateSchemaInjectionCode(
+  injectionTarget: string,
+  description: string,
+  properties: PropertyInfo[],
+  readOnly: boolean
+): string;
+```
+
+See [packages/webmcp-core/src/index.ts](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/src/index.ts) for the full surface.
+
+## Ecosystem
+
+`webmcp-nexus-core` is part of the WebMCP Nexus toolchain. The full set of published packages:
+
+| Package                                                                                    | Purpose                                                       |
+| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk)                       | Runtime SDK exposing `registerGlobalTools` / `useWebMcpTools` |
+| **`webmcp-nexus-core`** (this package)                                                     | Build-time core: TS extraction + JSON Schema generation       |
+| [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)       | Vite build plugin (built on this package)                     |
+| [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) | Webpack build plugin (built on this package)                  |
+
+## Links
+
+- 📦 **Main repo on GitHub**: [alibaba/webmcp-nexus](https://github.com/alibaba/webmcp-nexus)
+- 📖 **Full documentation**: [README](https://github.com/alibaba/webmcp-nexus#readme)
+- 🌐 **WebMCP standard**: [webmcp.org](https://webmcp.org)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/alibaba/webmcp-nexus/issues)
+
+## License
+
+[MIT](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE) © Alibaba

package/README.md

@@ -0,0 +1,178 @@
+<div align="center">
+
+# webmcp-nexus-core
+
+**WebMCP Nexus 的构建时核心 —— 基于 `ts-morph` 的 TypeScript 类型抽取与 JSON Schema 生成引擎。**
+
+[![npm version](https://img.shields.io/npm/v/webmcp-nexus-core.svg)](https://www.npmjs.com/package/webmcp-nexus-core)
+[![npm downloads](https://img.shields.io/npm/dm/webmcp-nexus-core.svg)](https://www.npmjs.com/package/webmcp-nexus-core)
+[![license](https://img.shields.io/npm/l/webmcp-nexus-core.svg)](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE)
+
+简体中文 | [English](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/README.en.md)
+
+</div>
+
+---
+
+## 目录
+
+- [简介](#简介)
+- [核心特性](#核心特性)
+- [优势](#优势)
+- [安装](#安装)
+- [使用示例](#使用示例)
+- [API 概览](#api-概览)
+- [生态包](#生态包)
+- [相关链接](#相关链接)
+- [许可证](#许可证)
+
+## 简介
+
+`webmcp-nexus-core` 是 [WebMCP Nexus](https://github.com/alibaba/webmcp-nexus) 工具链的**构建时核心包**，负责：
+
+1. 使用 [`ts-morph`](https://ts-morph.com/) 静态分析源码中标记为 WebMCP 工具的函数；
+2. 从函数的 **TypeScript 类型 + JSDoc** 反推出符合 [JSON Schema](https://json-schema.org/) 的工具描述；
+3. 生成注入代码，在每个工具函数对象上挂载 `__webmcpSchema` 字段，供运行时 SDK 读取并注册到 `navigator.modelContext`。
+
+它本身**不是给最终用户直接使用的包**，而是被 [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus) 与 [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) 共享的底层引擎。如果你正在编写**自定义的构建工具集成**（如 Rspack、Rollup、esbuild 插件），可以直接复用这个包。
+
+## 核心特性
+
+- 🔬 **基于 `ts-morph` 的静态类型分析** —— 函数签名 = JSON Schema，单一事实源。
+- 🪶 **零运行时开销** —— 所有 schema 在构建时生成，运行时无任何反射 / 解析成本。
+- 📦 **独立可复用** —— 与具体打包器解耦，提供纯函数式 `transformCode(code, filePath, options?)` 接口。
+- 🔁 **逆向追踪** —— 从 `registerGlobalTools` / `useWebMcpTools` 的调用点向上追溯到函数定义，工具函数本身不需要任何标记。
+- 🧩 **支持丰富的 TypeScript 类型** —— 基础类型、字面量联合（→ `enum`）、可选属性、嵌套对象（递归 ≤3 层）等。
+- 🛠️ **Alias 解析** —— 支持 `import * as api from '@alias/xxx'` 形式的模块说明符解析（兼容 webpack `$` 精确匹配语法）。
+
+## 优势
+
+| 维度       | 业内常见做法                  | webmcp-nexus-core                         |
+| ---------- | ----------------------------- | ----------------------------------------- |
+| Schema 来源 | 手写 JSON Schema 与 TS 类型双源维护 | **基于 TS 类型自动反推**，单一事实源     |
+| 运行时成本 | 装饰器 / 反射 / 包装函数      | **零运行时开销**——所有 schema 构建期注入 |
+| 生态绑定   | 通常与某一打包器深度耦合      | **打包器无关**——核心算法纯函数式可复用 |
+| 类型变更同步 | 需手动维护类型与 schema 一致 | TS 类型即权威源，编辑器即时反馈        |
+
+## 安装
+
+```bash
+# pnpm（推荐）
+pnpm add webmcp-nexus-core
+
+# npm
+npm install webmcp-nexus-core
+
+# yarn
+yarn add webmcp-nexus-core
+```
+
+> 大多数用户**不需要**直接安装这个包；安装 [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus) 或 [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) 时它会作为依赖自动引入。
+
+## 使用示例
+
+### 在自定义构建工具中调用
+
+> **重要**：`transformCode` 仅会处理**包含 `registerGlobalTools` / `useWebMcpTools` 调用**的源文件，并从这些调用向上追溯到工具函数定义。注入代码会插入在第一个注册调用之前，而不是工具函数定义文件中。
+
+```ts
+import { transformCode } from 'webmcp-nexus-core';
+
+// 假设这是项目入口文件 src/main.ts 的内容
+const code = `
+import { registerGlobalTools } from 'webmcp-nexus-sdk';
+import * as queries from './tools/queries';
+
+registerGlobalTools(queries);
+`;
+
+const result = transformCode(code, '/abs/path/to/project/src/main.ts', {
+  projectRoot: '/abs/path/to/project',
+  alias: { '@': '/abs/path/to/project/src' },
+});
+
+if (result.transformed) {
+  // result.code 在 registerGlobalTools 调用之前注入了 queries.* 各函数的 __webmcpSchema
+  console.log(result.code);
+}
+```
+
+注入产物（示意，来自 [`generateSchemaInjectionCode`](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/src/schema-generator.ts)）：
+
+```ts
+import { registerGlobalTools } from 'webmcp-nexus-sdk';
+import * as queries from './tools/queries';
+
+// [webmcp-nexus-core] 构建时注入的 schema 元数据
+queries.searchTasks.__webmcpSchema = {
+  "description": "根据关键词搜索任务。",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "搜索关键词" },
+      "limit": { "type": "number", "description": "返回数量上限（默认 50）" }
+    },
+    "required": ["query"]
+  },
+  "readOnly": true
+};
+
+registerGlobalTools(queries);
+```
+
+> 注入的 schema 仅含 `description` / `inputSchema` / `readOnly` 三个字段。运行时由 [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk) 读取并转换为 `navigator.modelContext.registerTool()` 所需的格式（如 `readOnly` → `annotations.readOnlyHint`）。
+
+## API 概览
+
+```ts
+// 高层 API：一次性完成提取 + 注入
+export function transformCode(
+  code: string,
+  filePath: string,
+  options?: TransformOptions
+): TransformResult;
+
+// 底层 API（高级用户）
+export function extractToolsFromFile(
+  fileContent: string,
+  filePath: string,
+  projectRoot?: string,
+  alias?: AliasMap
+): ExtractionResult | null;
+
+export function generateSchema(
+  properties: PropertyInfo[],
+  description?: string
+): JsonSchema;
+
+export function generateSchemaInjectionCode(
+  injectionTarget: string,
+  description: string,
+  properties: PropertyInfo[],
+  readOnly: boolean
+): string;
+```
+
+详见 [packages/webmcp-core/src/index.ts](https://github.com/alibaba/webmcp-nexus/blob/main/packages/webmcp-core/src/index.ts)。
+
+## 生态包
+
+`webmcp-nexus-core` 是 WebMCP Nexus 工具链的一部分。完整的发布包列表：
+
+| 包                                                                                         | 用途                                                  |
+| ------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| [`webmcp-nexus-sdk`](https://www.npmjs.com/package/webmcp-nexus-sdk)                       | 运行时 SDK，提供 `registerGlobalTools` / `useWebMcpTools` |
+| **`webmcp-nexus-core`** （本包）                                                            | 构建时核心：TS 类型抽取 + JSON Schema 生成              |
+| [`vite-plugin-webmcp-nexus`](https://www.npmjs.com/package/vite-plugin-webmcp-nexus)       | Vite 构建插件（基于本包）                              |
+| [`webpack-plugin-webmcp-nexus`](https://www.npmjs.com/package/webpack-plugin-webmcp-nexus) | Webpack 构建插件（基于本包）                           |
+
+## 相关链接
+
+- 📦 **GitHub 主仓库**：[alibaba/webmcp-nexus](https://github.com/alibaba/webmcp-nexus)
+- 📖 **完整文档**：[README](https://github.com/alibaba/webmcp-nexus#readme)
+- 🌐 **WebMCP 标准**：[webmcp.org](https://webmcp.org)
+- 🐛 **Issues**：[GitHub Issues](https://github.com/alibaba/webmcp-nexus/issues)
+
+## 许可证
+
+[MIT](https://github.com/alibaba/webmcp-nexus/blob/main/LICENSE) © Alibaba

package/package.json

@@ -1,7 +1,24 @@
 {
   "name": "webmcp-nexus-core",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Core logic for WebMCP build plugins - TypeScript type extraction and JSON Schema generation",
+  "license": "MIT",
+  "keywords": [
+    "webmcp",
+    "mcp",
+    "model-context-protocol",
+    "ai-tools",
+    "typescript",
+    "json-schema",
+    "type-extraction",
+    "build-plugin"
+  ],
+  "homepage": "https://github.com/alibaba/webmcp-nexus/tree/main/packages/webmcp-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alibaba/webmcp-nexus.git",
+    "directory": "packages/webmcp-core"
+  },
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",