# browser-mcp-client

**Repository Path**: mofum/browser-mcp-client

## Basic Information

- **Project Name**: browser-mcp-client
- **Description**: Model Context Protocol (MCP) 浏览器客户端库，用于调试或调用MCP协议的服务器
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-30
- **Last Updated**: 2025-10-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: MCP, mcp-client, JavaScript, browser

## README

# MCP Client

<p align="center">
  Model Context Protocol (MCP) 客户端库，用于与支持MCP协议的服务器进行高效通信
</p>

<p align="center">
  <a href="#-项目介绍">📖 项目介绍</a> •
  <a href="#-功能特点">✨ 功能特点</a> •
  <a href="#-项目结构">📁 项目结构</a> •
  <a href="#-快速开始">🚀 快速开始</a> •
  <a href="#-使用示例">💻 使用示例</a> •
  <a href="#-支持的连接类型">🔌 支持的连接类型</a> •
  <a href="#-依赖">📦 依赖</a>
</p>

## 📖 项目介绍

MCP Client 是一个功能强大的客户端库，专门设计用于与支持 Model Context Protocol 的服务器进行无缝通信。它提供了多种现代化的连接方式，包括 SSE (Server-Sent Events)、Streamable HTTP 和 WebSocket，使开发者能够根据应用需求灵活选择最适合的通信方式。

![VSCode风格的MCP客户端演示界面](examples/vscode-layout-demo/scrent.png)

## ✨ 功能特点

- **多协议支持**：集成了 SSE、Streamable HTTP 和 WebSocket 三种通信协议
- **统一接口**：提供一致的客户端 API，简化跨协议开发体验
- **完整请求/响应流程**：支持标准的请求-响应模式
- **会话管理**：内置会话状态维护机制
- **安全认证**：支持多种认证方式，保障通信安全
- **能力声明**：客户端可声明自身能力，服务器据此提供定制化服务
- **TypeScript 支持**：完整的类型定义，提供开发时类型检查与自动补全
- **AJV 验证**：使用 Ajv 作为主要的 JSON Schema 验证库，提供更强大的模式验证能力
- **轻量级设计**：优化的代码结构，最小化依赖

## 📁 项目结构

```
├── src/                     # 源代码目录
│   └── libs/                # 核心库文件（详见 <mcfile name="README.md" path="src/libs/README.md"></mcfile>）
│       ├── client/          # 客户端实现
│       ├── shared/          # 共享工具和协议定义
│       ├── types.d.ts       # TypeScript类型定义
│       ├── types.d.ts.map   # TypeScript类型映射文件
│       ├── types.js         # JavaScript类型定义
│       └── types.js.map     # JavaScript类型映射文件
├── examples/                # 示例代码
│   ├── sse-demo/            # SSE连接示例
│   ├── streamable-demo/     # Streamable连接示例  
│   ├── websocket-demo/      # WebSocket连接示例
│   └── vscode-layout-demo/  # VSCode风格的综合演示界面
├── electron/                # Electron应用源码（详见 <mcfile name="README.md" path="electron/README.md"></mcfile>）
├── electron-dist/           # Electron应用构建输出（详见 <mcfile name="README.md" path="electron-dist/README.md"></mcfile>）
├── package.json             # 项目配置和依赖
├── package-lock.json        # 依赖锁定文件
├── webpack.config.js        # Webpack构建配置
├── webpack.client.config.js # 客户端库专用Webpack配置
└── webpack.electron.config.js # Electron应用构建配置
```

## 🚀 快速开始

### 安装依赖

```bash
# 使用npm安装
npm install
```

### 构建项目

```bash
# 构建客户端库
npm run build

# 构建Electron应用
npm run electron:build
```

### 开发模式

```bash
# 启动Web开发服务器（端口8000）
npm run dev

# 启动Electron开发模式
npm run electron:dev
```

### Electron打包

```bash
# 打包当前平台
npm run electron:pack

# 打包Windows平台
npm run electron:pack:win

# 打包macOS平台
npm run electron:pack:mac

# 打包Linux平台
npm run electron:pack:linux
```

**注意**：当前版本不支持一次性打包所有平台的命令。


## 💻 使用示例

### 基本用法

以下是创建MCP客户端并发送请求的基本示例：

```javascript
// 导入客户端和传输层
import { Client } from "./src/libs/client/index.js";
import { SSEClientTransport } from "./src/libs/client/sse.js";

// 创建客户端实例
const client = new Client({
    name: "browser-client",
    version: "1.0.0"
});

// 创建传输层
const transport = new SSEClientTransport("http://localhost:8081/sse");

// 连接传输层并初始化客户端
await client.connect(transport);

// 发送请求
const result = await client.request("method.name", { param1: "value1" });
console.log("请求结果:", result);

// 使用便捷方法（根据服务器支持的能力）
// await client.complete({ prompt: "Hello, world!" });
// await client.ping();
// await client.setLoggingLevel("debug");
// const tools = await client.listTools();

// 关闭客户端连接
// await client.close();
```

### 认证方式

MCP客户端支持OAuth 2.0认证，可以通过实现`OAuthClientProvider`接口来自定义认证流程：

```javascript
// 创建带认证的传输层
const authProvider = {
    // 授权后重定向URL
    get redirectUrl() {
        return window.location.origin + window.location.pathname;
    },
    // 客户端元数据
    get clientMetadata() {
        return {
            client_name: "My MCP Client",
            scope: "read write"
        };
    },
    // 保存客户端信息（动态注册时使用）
    async saveClientInformation(clientInfo) {
        localStorage.setItem('clientInfo', JSON.stringify(clientInfo));
    },
    // 获取已保存的客户端信息
    async clientInformation() {
        const info = localStorage.getItem('clientInfo');
        return info ? JSON.parse(info) : undefined;
    },
    // 保存令牌
    async saveTokens(tokens) {
        localStorage.setItem('tokens', JSON.stringify(tokens));
    },
    // 获取已保存的令牌
    async tokens() {
        const tokens = localStorage.getItem('tokens');
        return tokens ? JSON.parse(tokens) : undefined;
    },
    // 重定向到授权页面
    redirectToAuthorization(authorizationUrl) {
        window.location.href = authorizationUrl.href;
    },
    // 保存PKCE验证器
    async saveCodeVerifier(codeVerifier) {
        localStorage.setItem('codeVerifier', codeVerifier);
    },
    // 获取PKCE验证器
    async codeVerifier() {
        return localStorage.getItem('codeVerifier') || '';
    },
    // 处理授权失败时的凭据失效
    async invalidateCredentials(scope) {
        if (scope === 'tokens' || scope === 'all') {
            localStorage.removeItem('tokens');
        }
        if (scope === 'client' || scope === 'all') {
            localStorage.removeItem('clientInfo');
        }
    }
};

// 创建带认证的传输层
const transport = new SSEClientTransport("http://localhost:8081/sse", {
    authProvider
});

// 连接传输层并初始化客户端（会自动处理认证流程）
await client.connect(transport);

// 检查URL中是否有授权码（授权回调时使用）
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
if (code) {
    // 如果URL中有授权码，使用它完成认证流程
    await auth(authProvider, {
        serverUrl: "http://localhost:8081/sse",
        authorizationCode: code
    });
    // 清除URL中的授权码
    window.history.replaceState({}, document.title, window.location.pathname);
}
```

### 运行示例项目

项目包含多个示例，展示了不同连接方式的使用方法：

| 示例目录 | 描述 | 特点 |
|----------|------|------|
| `examples/sse-demo/` | SSE连接示例 | 适合单向服务器推送场景 |
| `examples/streamable-demo/` | Streamable HTTP连接示例 | 支持流式HTTP响应 |
| `examples/websocket-demo/` | WebSocket连接示例 | 提供双向实时通信能力 |
| `examples/vscode-layout-demo/` | VSCode风格的综合演示界面 | 完整的UI演示，展示所有连接方式 |

您可以使用以下命令启动开发服务器直接访问示例：

```bash
npm run dev
```

这将自动打开浏览器并访问 http://localhost:8000/examples/vscode-layout-demo/ 查看VSCode风格的综合演示。

## 🔌 支持的连接类型

MCP Client 支持多种连接方式，满足不同应用场景的需求：

| 连接类型 | 描述 | 适用场景 |
|---------|------|---------|
| **SSE (Server-Sent Events)** | 单向服务器推送协议 | 接收服务器事件流、通知更新、状态监控 |
| **Streamable HTTP** | 可流式传输的HTTP连接 | 大型数据传输、渐进式内容加载、长轮询替代方案 |
| **WebSocket** | 双向实时通信协议 | 实时聊天、游戏、协作工具、需要频繁交互的应用 |

## 🛠️ 客户端能力

MCP Client 实现了客户端能力声明机制，使客户端能够向服务器表明其支持的功能和特性。服务器可以根据这些信息调整其行为，提供更加个性化的服务。

### 能力声明示例

```javascript
// 声明客户端能力
client.declareCapabilities({
  stream: true,          // 支持流式处理
  largePayload: true,    // 支持大 payload
  compression: ['gzip', 'deflate'], // 支持的压缩算法
  authentication: ['oauth2', 'basic'] // 支持的认证方式
});

// 获取当前声明的能力
const capabilities = client.getCapabilities();
console.log('客户端能力:', capabilities);
```

### 能力协商流程

1. 客户端初始化后声明其能力
2. 服务器接收并解析客户端能力声明
3. 服务器根据客户端能力调整响应策略
4. 客户端接收服务器响应时，可根据服务器支持的能力调整自身行为

## 📦 依赖

MCP Client 依赖以下核心库：

| 依赖名称 | 版本 | 用途 | 来源 |
|---------|------|------|------|
| [ajv](https://github.com/ajv-validator/ajv) | ^8.17.1 | JSON Schema验证库 | GitHub |
| [pkce-challenge](https://github.com/curityio/pkce-challenge) | ^5.0.0 | PKCE挑战生成工具 | GitHub |
| [zod](https://github.com/colinhacks/zod) | ^4.1.11 | TypeScript-first schema声明和验证库（备用） | GitHub |

## 🛠️ 开发工具

项目使用以下开发工具和技术栈：

- [Webpack](https://webpack.js.org/) - 模块打包工具
- [Babel](https://babeljs.io/) - JavaScript编译器，支持最新JS特性
- [TypeScript类型定义](https://www.typescriptlang.org/) - 提供类型定义文件，支持TypeScript开发

## 🌐 跨域处理

在使用MCP客户端库与不同域名的服务器进行通信时，可能会遇到跨域资源共享(CORS)限制。以下是处理跨域问题的几种常见方式，按推荐程度排序：

### 1. 使用Electron版本（推荐）

最简单的解决方案是使用项目提供的Electron版本，它自动忽略了所有跨域限制：

```bash
# 构建并运行Electron应用
npm run electron:build
npm run electron:dev
```

详细信息请参考 <mcfile name="README.md" path="electron/README.md"></mcfile>。

### 1. 服务器端配置CORS

最直接且推荐的解决方案是在服务器端配置CORS，允许来自客户端域名的请求。服务器需要设置适当的响应头，如：

```
Access-Control-Allow-Origin: *  # 或指定允许的域名
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Allow-Credentials: true  # 如果需要发送凭证
```

### 2. 开发环境使用代理服务器

在开发环境中，可以使用webpack等工具配置代理服务器转发请求，绕过浏览器的跨域限制：

```javascript
// webpack.config.js
module.exports = {
  // ...
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:8081',
        changeOrigin: true,
        pathRewrite: {
          '^/api': ''
        }
      }
    }
  }
};
```

### 3. 生产环境配置反向代理

在生产环境中，推荐在后端服务器配置反向代理，将客户端请求转发到目标服务器。以下是使用Nginx配置反向代理的完整示例：

```nginx
server {
  listen 80;
  server_name yourdomain.com;
  
  # 可选：重定向HTTP到HTTPS
  # return 301 https://$server_name$request_uri;
  
  location /api {
    proxy_pass http://target-server.com;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # WebSocket支持（如果需要）
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
  
  # 静态资源服务
  location / {
    root /path/to/your/static/files;
    index index.html;
    try_files $uri $uri/ /index.html;
  }
}
```

## 📝 许可证

该项目采用 **MIT 许可证** - 详见 [LICENSE](LICENSE) 文件。

## 👥 作者与贡献

- **作者**：[Mofum] - Mofum

欢迎提交Issue和Pull Request来帮助改进这个项目！