open-index/open-npm huggingface dataset:
npm package: @opentiny/tiny-agent-mcp-client-chat
Description: 一个基于 TypeScript 的 Model Context Protocol (MCP) 客户端实现，支持与 LLM 集成。
Latest version: 0.1.0-alpha.5

# MCP Client Chat

一个基于 TypeScript 的 Model Context Protocol (MCP) 客户端实现，支持与 LLM 集成。

- **安装**

```bash
npm install @opentiny/tiny-agent-mcp-client-chat --save
```

- **参数说明**

  - `llmConfig(object)`: LLM 配置项

    - `url(string)`: AI 平台 API 接口地址
    - `apiKey(string)`: AI 平台的 API Key
    - `model(string)`: 模型名称
    - `systemPrompt(string)`: 系统提示词

  - `maxIterationSteps(number)`: Agent 最大迭代步数

  - `mcpServersConfig(object)`: mcp-server 配置项

    - `mcpServers(object)`: mcp-server 基础配置

      - `<serverName(string)>`: mcp-server 服务名

        - `url(string)`: mcp-server 连接地址
        - `headers(object)`: 请求头
        - `timeout(number)`: 超时时长

- **示例**

```typescript
import express from "express";
import cors from "cors";
import { createMCPClientChat } from "@opentiny/tiny-agent-mcp-client-chat";

async function main() {
  const app = express();
  app.use(cors());
  app.use(express.json());

  app.post("/chat", async (req, res) => {
    const mcpClientChat = await createMCPClientChat({
      llmConfig: {
        url: "https://openrouter.ai/api/v1/chat/completions",
        apiKey: "<your-api-key>",
        model: "mistralai/mistral-7b-instruct:free",
        systemPrompt: "You are a helpful assistant with access to tools.",
      },
      maxIterationSteps: 3,
      mcpServersConfig: {
        mcpServers: {
          "localhost-mcp": {
            url: `xxx`,
            headers: {},
            timeout: 60
          },
          "localhost-mcp2": {
            url: `xxx2`,
            headers: {},
            timeout: 60
          },
        },
      },
    });

    try {
      // 流式数据返回
      const streamResponse = await mcpClientChat.chat("your question...");

      streamResponse.pipe(res);
    } catch (error) {
      // 错误处理
    }
  });
}

main();
```
npm package: @opentiny/tiny-agent-mcp-connector
Description: 本质上，ConnectorCenter 是用于维护管理通信层多端的管理器
Latest version: 0.1.0-alpha.5

# MCP Connector

## 核心概念

### ConnectorCenter

#### 概念

本质上，ConnectorCenter 是用于维护管理通信层多端的管理器

#### 方法

##### getClient

获取通信层端点
通常用于 ProxyServer 接收到 MCP Client 的请求时会使用该 API 获取已建立起通信的客户端句柄

- **示例**

```typescript
const connectorCenter = new ConnectorCenter();
connectorCenter.getClient('clientId');
```

##### setClient

通常用于建立通信时，建立 Client 的映射

- **示例**

```typescript
const connectorCenter = new ConnectorCenter();
connectorCenter.setClient('clientId', socket);
```

##### removeClient

通常用于通信连接断开时移除 Client

- **示例**

```typescript
const connectorCenter = new ConnectorCenter();
connectorCenter.removeClient('clientId');
```

### ConnectorEndpoint

基于IConnectorEndpoint协议标准的通信层，用于ClientID注册以及任务调度通信，接下来以WebSocket通信为例子介绍

#### WebsocketClientEndpoint

基于 IConnectorEndpoint 协议标准的 WebSocket 通信层客户端

##### 使用

```typescript
const webSocketClientEndpoint = new WebSocketClientEndpoint({ url: 'ws://localhost:8082' });
```

##### 方法

###### start

启动 WebSocket 客户端

- **示例**

```typescript
webSocketClientEndpoint.start();
```

###### close

关闭 WebSocket 客户端连接

- **示例**

```typescript
webSocketClientEndpoint.close();
```

###### send

客户端发送消息

- **示例**

```typescript
webSocketClientEndpoint.send();
```

#### WebsocketServerEndpoint

基于 IConnectorEndpoint 协议标准的 WebSocket 通信层服务端

##### 说明

WebsocketServerEndpoint 只负责消息的处理以及端点的关闭，初始化过程详见 WebsocketEndpointServer API 文档

##### 使用

```typescript
const webSocketServerEndpoint = new WebSocketServerEndpoint(ws, clientId, serverId);
```

##### 方法

###### start

启动 WebSocket 服务端，处理消息接收

- **示例**

```typescript
webSocketServerEndpoint.start();
```

###### close

关闭 WebSocket 服务端连接

- **示例**

```typescript
webSocketServerEndpoint.close();
```

###### send

服务端发送消息

- **示例**

```typescript
webSocketServerEndpoint.send();
```

### EndpointTransport

#### 介绍

EndpointTransport 实现了 MCP 标准化的 Transport 协议，内置通信层端点用于 MCP Server 与通信层进行访问

#### 示例

以下用 WebSocket 通信作为示例，入参为工厂方法，用以构造通信层端点

```typescript
function getWebSocketClientEndpoint() {
  return new WebSocketClientEndpoint({ url: 'ws://localhost:8082' });
}

const endpointTransport = new EndpointTransport(getWebSocketClientEndpoint);
const mcpServer = new McpServer({
  name: 'MCP Service',
  version: '1.0.0',
});

mcpServer.connect(endpointTransport);
```

#### 拓展

- 如果需要使用其他通信层协议，可以替换 EndpointTransport 构造函数入参的工厂方法来构造其他通信层实例。
- 需要注意的是需要自行开发维护相应的通信层服务端，通信层需要以 IConnectorEndpoint 协议为标准
npm package: @opentiny/tiny-agent-mcp-proxy-server
Description: 一个基于 MCP Connector Endpoint 的远程 MCP Server 代理方案，可以对接各类 ServerTransport。
Latest version: 0.1.0-alpha.5

# MCP Proxy Server

一个基于 MCP Connector Endpoint 的远程 MCP Server 代理方案，可以对接各类 ServerTransport。

## 用法

```typescript
const server = new ProxyServer();
server.connect(new SSEServerTransport(...));
server.setEndpoint(new WebSocketServerEndpoint(...));
```

## 方法

### connect

用于连接 MCPServer 端 Transport

- **详细信息**

  连接到已有的 SSEServerTransport / StreamableHTTPServerTransport 等 MCPServer 端 Transport，将会接收Transport的消息与Endpoint消息互相发送

- **示例**

```typescript
const server = new ProxyServer();
server.connect(new SSEServerTransport(...));
```

### setEndpoint

设置连接到 MCP Connector 的 Endpoint， 将通过 Endpoint与远程 MCPServer 通信

- **示例**

```typescript
const server = new ProxyServer();
server.setEndpoint(new WebSocketServerEndpoint(...))

```

### setVerifyCode

设置验证信息

- **详细信息**

用于回传验证信息，保证消息是用户主动发送的， 验证信息目前的方案会放在extra.authInfo.extra.verifyCode

- **示例**

```typescript
import { v4 as uuidv4 } from 'uuid';
const server = new ProxyServer();
const verifyCode = uuidv4();
server.setVerifyCode(verifyCode);
```
npm package: @opentiny/tiny-agent-mcp-service
Description: mcp service
Latest version: 0.1.0-alpha.5

# McpService

提供应用端端 MCP 服务，支持使用 MCPServer 注册工具等，通过覆写 MCPServer 部分发那个发支持了验证功能和先连接`Transport`后注册工具动态注册功能。

- **用法**

```typescript
const mcp = new McpService();
const mcpServer = mcp.mcpServer;
mcpServer.connect(...);
mcpServer.tool(...);
```

## 属性

### mcpServer(McpServer)

McpServer实例

## 方法

### setValidator

设置验证器， 用于验证任务时用户授权的

- **参数**

validator(McpValidator)
npm package: @opentiny/tiny-agent-mcp-service-vue
Description: 提供 Vue 应用等快速用法
Latest version: 0.1.0-alpha.5

# McpService Vue

提供 Vue 应用等快速用法

## 方法

### setupMcpService

初始化 McpService，并提供Vue依赖注入，返回 McpService 实例。

- **用法**

```javascript
// App。vue
const mcp = setupMcpService();
mcp.mcpServer.connect(...);
```

### useMcpService

自动注入 McpService， 并提供一个`tool`方法能自动章组件挂载和移除自动注册与移除

- **用法**

```javascript
// component.vue
const { tool } = useMcpService();
tool(...); //自动在组件挂载等时候注册工具，组件移除等时候移除工具
```

#### 返回值

mcp： McpService实例
tool： 工具注册方法，会自动加载时注册卸载时移除
npm package: @opentiny/tiny-agent-task-mcp
Description: Tiny Agent MCP Task
Latest version: 0.1.0-alpha.5

# McpToolParser

用于将 JSON 格式的静态工具填充参数转换为符合 MCP 协议标准的 MCP Tool

## 方法

### replaceInstructionParamValue

使用真实参数替换静态工具 JSON 数据中的参数占位符

#### 示例

```typescript
const doTask = () => {
  console.log('execute task...');
};
const mcpToolParser = new McpToolParser(doTask);
const instruction: InstructionSchema = {
  action: '注册Tool',
  params: {
    name: '{{name}}',
  },
};

mcpToolParser.replaceInstructionParamValue(instruction, 'name', 'queryTool');

console.log(instruction); // { action: '注册Tool', params: { name: 'queryTool' } }
```

## extractTool & extractAllTools

将 JSON 格式的静态工具填充参数转换为符合 MCP 协议标准

#### 示例

```typescript
const doTask = () => {
  console.log('execute task...');
};
const mcpToolParser = new McpToolParser(doTask);

/**
 * extractTool 将单个工具进行标准化
 * extractAllTools 批量将多个工具进行标准化
 * mcpToolJson 为JSON格式的静态工具集 详细可参考demo目录下的mcp-tool.json
 * mcpTool 即为符合MCP协议标准的MCP Tool
 **/
const mcpTool = mcpToolParser.extractTool(mcpToolJson);
const mcpTools = mcpToolParser.extractAllTools(mcpToolsJson);
```

## getTaskOutputSchema

获取 MCP Tool OutputSchema

#### 示例

```typescript
const doTask = () => {
  console.log('execute task...');
};
const mcpToolParser = new McpToolParser(doTask);
const taskOutputSchema = mcpToolParser.getTaskOutputSchema();
```
npm package: @opentiny/tiny-agent-task-runtime-service
Description: 用于执行相关页面操作的逻辑函数。
Latest version: 0.1.0-alpha.5

# tiny-agent 运行时服务层

## 核心概念

### Action

用于执行相关页面操作的逻辑函数。

```ts
const click: Action = {
  name: ActionType.CLICK,
  execute: async (params, context) => {
    const elements = await findElements(params.selector, params.timeout);
    await forEachElement(elements, async (element) => {
      await simulateClick(element);
    });
    return {
      status: 'success',
    };
  },
};
```

### Instruction

指导页面进行相关操作的单条指令。

```json
{ "action": "click", "params": { "selector": "#submitBtn" } }
```

### Task

一个带有 ID 的指令集。

```json
{
  "id": "{{uniqueId}}",
  "instructions": [
    { "action": "vue_push", "params": { "url": "/addPath" } },
    { "action": "click", "params": { "selector": "#submitBtn" } }
  ]
}
// 跳转示例
{
  "id": "123",
  "instructions": [
    { "action": "vue_push", "params": { "to": "/vue-pro/userManager/allInfo" } },
    { "action": "click", "params": { "selector": ".user-add-btn > button" } }
  ]
}

```

## 基本用法

```js
import { createScheduler } from '@opentiny/tiny-agent-task-runtime-service';
import {
  DomActions,
  FormActions,
  VueRouterActions,
  GuideActions,
  AxiosActions,
} from '@opentiny/tiny-agent-task-action-lib';

const baseActions = [...DomActions, ...FormActions];
const initContext = {
  $router: router,
};

const { taskScheduler, actionManager } = createScheduler(
  baseActions,
  initContext
);

// 通过actionManager动态新增action
const extendActions = [...VueRouterActions, ...GuideActions, ...AxiosActions];
actionManager.registerActions(extendActions);

// 动态添加上下文
taskScheduler.addContext({ $axiosConfig: { axios, timeout: 3000 } });

const taskDescription = {
  id: '123',
  instructions: [{ action: 'click', params: { selector: '#submitBtn' } }],
};
taskScheduler.pushTask(taskDescription);
```
npm package: @opentiny/tiny-agent-ui-components
Description: 为目标元素添加呼吸效果
Latest version: 0.1.0-alpha.5

# tiny-agent 基础 UI 库

## breathe

为目标元素添加呼吸效果

### 添加以及移除呼吸效果

```js
const breatheBtn = document.getElementById('breathe-btn');
addBreathe(breatheBtn);

// 移除呼吸效果
removeBreathe(breatheBtn);
```

## floatElement

添加浮动元素，如 tooltip、 modal、popover 等元素

### 添加 tooltip

```js
// 示例1: 简单文本 tooltip
const tooltipBtn = document.getElementById('tooltip-btn');
if (tooltipBtn) {
  const tooltip = addTooltip(tooltipBtn, '这是一个简单的文本提示');

  // 可以稍后通过 tooltip.destroy() 移除
}
```

### 添加 popup

```js
// 示例 2: 点击触发的 popup
const clickPopupBtn = document.getElementById('click-popup-btn');
if (clickPopupBtn) {
  const customContent = document.createElement('div');
  customContent.innerHTML =
    '<strong>点击触发的弹出内容</strong><p>点击外部区域关闭</p>';
  customContent.style.padding = '5px';

  const popup = addPopup(clickPopupBtn, customContent, {
    placement: 'bottom',
    showArrow: true,
    arrowColor: '#007bff',
    className: 'custom-popup',
    triggerMode: 'click', // 默认值，可省略
  });

  // 可以通过 popup.isOpen() 检查状态
  // 可以通过 popup.destroy() 移除
}
```

### 手动控制的 popup

```js
// 示例 3: 手动控制的 popup
const manualBtn = document.getElementById('manual-btn');
const openPopupBtn = document.getElementById('open-popup-btn');

if (manualBtn && openPopupBtn) {
  const content = document.createElement('div');
  content.innerHTML =
    '<h4>手动控制的弹出框</h4><p>这个弹出框需要通过代码控制</p><button class="close-popup-btn">关闭</button>';

  // 创建手动控制的弹出框
  const popup = addPopup(manualBtn, content, {
    placement: 'right',
    closeOnClickOutside: false,
    closeOnEsc: true,
    triggerMode: 'manual', // 关键配置！使用手动触发模式
  });

  // 通过其他元素控制显示
  openPopupBtn.addEventListener('click', () => {
    popup.show();
  });

  // 找到关闭按钮并添加事件
  setTimeout(() => {
    const closeBtn = content.querySelector('.close-popup-btn');
    if (closeBtn) {
      closeBtn.addEventListener('click', () => {
        popup.hide();
      });
    }
  }, 100);
}
```