Session Bridge

会话桥

与MCP服务器共享浏览器会话-零API密钥、零密码、零OAuth设置。

SessionBridge是一个Chrome扩展程序，可以捕获您现有的浏览器会话（Cookie+CSRF令牌），并将其提供给本地MCP服务器。只需像往常一样通过浏览器登录，任何兼容的MCP服务器都可以使用该会话验证API调用。

______________________________________________________________________

目录

• 运作原理
• 先决条件
• 安装

- 第一步：安装Chrome扩展程序 - 步骤2：安装本机消息主机 - 步骤3：验证扩展是否正常工作

• 与ServiceNow MCP服务器配合使用

- 安装MCP服务器 - 配置Claude代码 - 配置Claude桌面 - 示例提示

• 添加自定义域
• 面向MCP开发人员的SDK
• 故障排除
• 建筑
• 安全
• 项目结构

______________________________________________________________________

运作原理

Chrome Browser (SSO session)
        │
        ▼
SessionBridge Extension ──► captures cookies + CSRF tokens
        │
        ▼ (native messaging)
Native Host ──► writes ~/.sessionbridge//session.json
        │
        ▼ (file read)
MCP Server ──► authenticates API calls using session data

1. 您可以像往常一样在Chrome中登录网站（例如ServiceNow）
2. 这 SessionBridge扩展 检测配置的域，捕获Cookie和CSRF令牌
3. 这 本机消息传递主机 将会话数据写入本地文件
4. 任何 MCP服务器 读取该文件以验证API调用-不需要凭据

______________________________________________________________________

先决条件

• 谷歌浏览器 （或基于Chromium的浏览器）
• Node.js v18或更高版本-- 通过nvm安装 或
• macOS 或 Linux （Windows支持即将推出）

______________________________________________________________________

安装

第一步：安装Chrome扩展程序

1. 克隆此存储库：

   git clone https://github.com/your-org/SessionBridge.git
   cd SessionBridge

1. 构建扩展：

   cd extension
   npm install
   npm run build

1. 在Chrome中加载扩展程序：

- 打开 chrome://extensions 在Chrome浏览器中 - 启用 开发人员模式 （在右上角切换） - 点击 “未包装装载” - 选择 extension/dist/ 目录 - SessionBridge扩展图标将出现在您的工具栏中

1. 复制您的 扩展ID --下一步您将需要它：

- 开 chrome://extensions，查找SessionBridge - ID是一个长字符串，如 olgdpopjjbbalilgblelgccmnldfnoel

步骤2：安装本机消息主机

原生消息主机是一个小型的Node.js脚本，用于连接Chrome和本地文件系统。

cd native-host
EXTENSION_ID=
 ./install.sh

或者在不提示环境变量的情况下运行：

cd native-host
./install.sh

安装程序将：

• 将主机脚本复制到 ~/.sessionbridge/
• 在Chrome中注册本机消息清单
• 创建 ~/.sessionbridge/ 具有安全权限的目录
• 使用预先配置的ServiceNow和Jira创建默认配置

安装后，完全退出并重新启动Chrome （macOS上的Cmd+Q，而不仅仅是关闭窗口）。

步骤3：验证扩展是否正常工作

1. 打开您已配置的网站（例如，您的ServiceNow实例）
2. 打开Chrome DevTools（F12或Cmd+Shift+I）
3. 在控制台中，查找：

   [SessionBridge] Domain matched: yourinstance.service-now.com → *.service-now.com
   [SessionBridge] Session captured for yourinstance.service-now.com

1. 验证会话文件是否已写入：

   cat ~/.sessionbridge/yourinstance.service-now.com/session.json

您应该看到带有Cookie、CSRF令牌和时间戳的JSON。

______________________________________________________________________

与ServiceNow MCP服务器配合使用

SessionBridge使用fork 梯队人工智能实验室/servicenow mcp 这增加了 session_bridge 身份验证支持。

安装MCP服务器

1. 克隆叉子：

   git clone https://github.com/Kalppatel000/servicenow-mcp.git
   cd servicenow-mcp

1. 安装依赖项（需要 紫外线):

   uv python install 3.11
   uv sync --python 3.11

或者使用pip：

   python3.11 -m venv .venv
   source .venv/bin/activate
   pip install -e .

配置Claude代码

创建一个 .mcp.json 项目根目录中的文件：

{
  "mcpServers": {
    "servicenow": {
      "command": "/path/to/servicenow-mcp/.venv/bin/python",
      "args": ["-m", "servicenow_mcp.cli"],
      "env": {
        "SERVICENOW_AUTH_TYPE": "session_bridge"
      }
    }
  }
}

就是这样。没有实例URL，没有用户名，没有密码。服务器会自动从SessionBridge会话文件中发现您的ServiceNow实例。

如果您有多个ServiceNow实例，请指定哪个实例：

{
  "mcpServers": {
    "servicenow": {
      "command": "/path/to/servicenow-mcp/.venv/bin/python",
      "args": ["-m", "servicenow_mcp.cli"],
      "env": {
        "SERVICENOW_AUTH_TYPE": "session_bridge",
        "SESSIONBRIDGE_DOMAIN": "myinstance.service-now.com"
      }
    }
  }
}

配置Claude桌面

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "servicenow": {
      "command": "/path/to/servicenow-mcp/.venv/bin/python",
      "args": ["-m", "servicenow_mcp.cli"],
      "env": {
        "SERVICENOW_AUTH_TYPE": "session_bridge"
      }
    }
  }
}

示例提示

配置后，重新启动Claude Code/Claude Desktop并尝试：

• 列出事件：

  Show me the 5 most recent incidents on my ServiceNow instance.
  Include the number, short description, priority, and current state.

• 创建事件：

  Create a new incident with short description "Test from SessionBridge"
  and description "Created via MCP using browser session auth" with priority 3.

• 查找用户：

  Find the user record for kalp.patel in ServiceNow.

• 搜索知识库：

  Search the knowledge base for articles about VPN setup.

______________________________________________________________________

添加自定义域

SessionBridge预先配置用于：

通过扩展弹出窗口

1. 点击Chrome工具栏中的SessionBridge图标
2. 点击 “+添加域”
3. 填写：

- 域模式： 例如。， *.example.com - CSRF选择器： 例如。， meta[name='csrf-token'] - CSRF标头名称： 例如。， X-CSRF-Token

1. 点击 保存

通过配置文件

编辑 ~/.sessionbridge/config.json:

{
  "domains": {
    "*.service-now.com": {
      "csrfSelectors": ["input[name='sysparm_ck']"],
      "csrfHeader": "X-UserToken",
      "refreshInterval": 600,
      "sessionTTL": 1800
    },
    "*.your-saas.com": {
      "csrfSelectors": ["meta[name='csrf-token']"],
      "csrfHeader": "X-CSRF-Token",
      "refreshInterval": 600,
      "sessionTTL": 3600
    }
  }
}

配置选项：

• csrfSelectors --CSS选择器，用于在页面DOM中查找CSRF标记
• csrfHeader --用于发送CSRF令牌的HTTP标头名称
• refreshInterval --重新捕获会话的频率（秒）
• sessionTTL --会话被视为新鲜的时间（秒）

______________________________________________________________________

面向MCP开发人员的SDK

如果您正在构建自己的MCP服务器并希望使用SessionBridge进行身份验证，请安装SDK：

cd sdk
npm install
npm run build

用法

import { readSession, validateSession, getAuthHeaders } from '@sessionbridge/sdk';

// Read session for a domain
const session = await readSession('yourinstance.service-now.com');

if (!session) {
  throw new Error('No active session. Open the site in Chrome first.');
}

// Check if session is still fresh
if (!validateSession(session)) {
  throw new Error('Session expired. Refresh by visiting the site in Chrome.');
}

// Get auth headers (Cookie + CSRF)
const headers = getAuthHeaders(session);
// Returns: { Cookie: "...", "X-UserToken": "..." }

const response = await fetch('https://yourinstance.service-now.com/api/now/table/incident', {
  headers,
});

API 参考

会话数据格式

interface SessionData {
  domain: string;       // e.g., "yourinstance.service-now.com"
  cookies: string;      // Cookie header string
  csrf: {
    token: string;      // CSRF token value
    header: string;     // Header name, e.g., "X-UserToken"
  } | null;
  user: {
    detected: boolean;
    displayName?: string;
    identifier?: string;
  } | null;
  timestamp: number;    // Capture time (milliseconds since epoch)
  ttl: number;          // Time-to-live in seconds
}

______________________________________________________________________

故障排除

Chrome控制台中出现“本机主机已退出”错误

原因： Chrome无法启动本机消息主机。

修复：

1. 验证是否安装了本机主机：

   cat ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.sessionbridge.native.json

1. 检查 path 指向现有文件：

   ls -la ~/.sessionbridge/native-host.sh

1. 确保在安装后完全重新启动Chrome（Cmd+Q，而不仅仅是关闭）
2. 检查主机日志：

   cat ~/.sessionbridge/host.log

扩展名与域匹配，但未创建会话文件

原因： 内容脚本正在运行，但服务工作程序或本机主机以静默方式失败。

修复：

1. 打开 chrome://extensions → Click “服务工作者” SessionBridge下
2. 检查控制台是否有错误消息
3. 确保中的扩展ID com.sessionbridge.native.json 火柴 chrome://extensions

会话文件存在，但MCP服务器无法进行身份验证

原因： 会话可能已过时或缺少CSRF令牌。

修复：

1. 检查会话新鲜度：

   cat ~/.sessionbridge/yourinstance.service-now.com/session.json | python3 -c "
   import json, sys, time
   s = json.load(sys.stdin)
   age = time.time() - s['timestamp']/1000
   print(f'Age: {int(age)}s, TTL: {s[\"ttl\"]}s, Fresh: {age /session.json     │
│  - Each domain gets its own session file                │
└─────────────────────────┬───────────────────────────────┘
                          │ File system
┌─────────────────────────▼───────────────────────────────┐
│  ~/.sessionbridge/                                      │
│  ├── config.json                                        │
│  ├── yourinstance.service-now.com/                      │
│  │   └── session.json                                   │
│  └── jira.atlassian.net/                                │
│      └── session.json                                   │
└─────────────────────────┬───────────────────────────────┘
                          │ File read
┌─────────────────────────▼───────────────────────────────┐
│  MCP Server (e.g., servicenow-mcp)                      │
│  - Reads session.json for the target domain             │
│  - Uses cookies + CSRF as auth headers                  │
│  - Auto-discovers instance URL from session files       │
└─────────────────────────────────────────────────────────┘

______________________________________________________________________

安全

• 会话文件是通过以下方式创建的 0600 权限（仅限所有者读/写）
• 会话目录 ~/.sessionbridge/ 用途 0700 权限
• 会话根据可配置的TTL过期（默认值：ServiceNow为30分钟）
• 不存储凭据，只存储随浏览器会话过期的会话Cookie
• 本机消息主机仅与注册的Chrome扩展程序通信（通过扩展程序ID验证）
• 会话数据永远不会离开你的机器——它会从Chrome浏览器传输到本地文件

______________________________________________________________________

项目结构

SessionBridge/
├── extension/                      # Chrome Extension (Manifest V3)
│   ├── manifest.json
│   ├── src/
│   │   ├── background.ts           # Service worker: cookie retrieval, native messaging
│   │   ├── content.ts              # Content script: CSRF detection, session trigger
│   │   ├── popup.ts                # Popup UI: domain management, status display
│   │   ├── popup.html
│   │   └── popup.css
│   ├── webpack.config.js
│   └── package.json
├── native-host/                    # Native Messaging Host
│   ├── sessionbridge-host.js       # Receives messages, writes session files
│   ├── install.sh                  # Cross-platform installer
│   └── com.sessionbridge.native.json  # Manifest template
├── sdk/                            # SDK for MCP server developers
│   ├── index.ts                    # readSession(), validateSession(), getAuthHeaders()
│   ├── types.ts                    # SessionData interface
│   └── package.json
├── .mcp.json                       # MCP server config for Claude Code
├── package.json
├── tsconfig.json
└── README.md

______________________________________________________________________

许可证

麻省理工学院