Local Ctx

本地Ctx

MCP服务器助手允许用户将标准STDIO服务器作为流式HTTP暴露给外部客户端。支持通过OAuth进行身份验证。 这允许您将本地运行的MCP服务器安全地暴露给基于云的客户端，如Claude.ai或ChatGPT，例如，可以用手机控制您的计算机（不是真的，因为他们的应用程序不支持MCP）。或者将计算机上的MCP服务器暴露给你的朋友或同事，熟人可能是一座太远的桥梁。

特性

• 使用stdio将子进程连接到可流式传输的HTTP端点
• 支持通过JWT令牌进行OAuth身份验证
• 多种配置方法（JSON文件、CLI参数、环境变量）

用法

使用npx（推荐）

# Basic usage with command-line arguments
npx @ilities/local-ctx --commands '[{"name":"memory","command":"npx -y @modelcontextprotocol/server-memory"}]' --port 8000

# Using a configuration file
npx @ilities/local-ctx --config ./my-config.json

# Using environment variables with custom port
PORT=9000 COMMANDS='[{"name":"memory","command":"npx -y @modelcontextprotocol/server-memory"}]' npx @ilities/local-ctx

开发模式/使用节点

git clone https://github.com/Ilities/local-ctx.git

# Install locally
npm install

# Build the project
npm run build

# Basic usage with command-line arguments
node dist/index.js --commands '[{"name":"memory","command":"npx -y @modelcontextprotocol/server-memory"}]' --port 8000

# Using a configuration file
node dist/index.js --config ./my-config.json

# Using environment variables with custom port
PORT=9000 COMMANDS='[{"name":"memory","command":"npx -y @modelcontextprotocol/server-memory"}]' node dist/index.js

配置方法

Local Ctx支持同时运行多个本地MCP服务器。它们都是根据提供的命令作为标准STDIO服务器启动的。

它们被公开为可流式传输的HTTP端点 该命令是基于配置中为命令指定的名称生成的.

例如命令：

{
  "name": "memento",
  "command": "npx -y @modelcontextprotocol/server-memory"
}

将公开可流式传输的HTTP server-memory 地址上的MCP服务器 http://localhost:8000/memento.

配置按以下优先级顺序加载（从高到低）：

1. 命令行参数
2. 环境变量
3. JSON配置文件

命令行选项

• --config, -c：JSON配置文件的路径
• --port, -p：服务器的端口号（默认值：8000）
• --commands：JSON命令字符串配置
• --authorizationServerUrl：OAuth授权服务器的URL

环境变量

• PORT：服务器的端口号
• COMMANDS：命令配置的JSON字符串数组

配置文件格式

使用指定路径 --config 选项a config.json 文件：

npx @ilities/local-ctx --config config.json

{
  "commands": [
    {
      "name": "memory",
      "command": "npx -y @modelcontextprotocol/server-memory"
    }
  ],
  "port": 8000,
  "oauth": {
    "authorizationServerUrl": "https://your-auth-server.example.com",
    "jwksPath": "/optional-jwks-path"
  }
}

命令配置

每个命令都需要以下属性：

• name：命令的唯一标识符（用作端点路径）
• command：用于启动MCP服务器的shell命令。运行该命令的工具需要存在于系统中（npx、uv、python等，具体取决于服务器）

OAuth配置

OAuth可以配置为保护您的端点：

• authorizationServerUrl：OAuth授权服务器的URL
• jwksPath：JWKS端点的可选路径（默认为标准路径，即 /oauth2/jwks)

配置OAuth后，服务器将自动：

• 在以下位置公开OAuth发现端点 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server
• 所有命令端点都需要有效的JWT承载令牌

身份验证设置

目前，该实用程序已使用WorkOS进行了测试。欢迎其他实施方式。

WorkOS

WorkOS是支持OAuth 2.1的IDPs之一（尽管与许多IDPs一样，仍然没有为所有客户端提供足够好的CORS标头支持）。保护暴露在外部的本地MCP服务器的设置相当简单。步骤如下：

1. 注册到WorkOS
2. 单击主页上的“设置AuthKit”按钮。 查看图片workos-main-page.webp
3. 逐步完成向导 查看图片workos-authkit-setup.webp
4. 在步骤4，设置 http://localhost:8000 （或您的端口配置）作为回调URL 查看图片workos-authkit-callback.webp
5. _（可选）_ 导航到左侧菜单上的“应用程序”。单击“创建应用程序” 查看图片workos-create-app.webp
6. _（可选）_ 在对话框中选择OAuth应用程序
7. _（可选）_ 将名称和描述添加到yout应用程序。启用PKCE。单击“创建应用程序” 查看图片workos-app-details.webp
8. _（可选）_ 添加 http://localhost:8000 作为应用程序的重定向URL 查看图片workos-redir-url.webp
9. 导航回左侧菜单上的应用程序，单击二级菜单上的“配置”，然后 启用 _动态客户端注册_ 查看图片workos-allow-dynamic-reg.webp
10. 禁用/启用所需的OAuth提供程序。您需要为每个对象创建OAuth客户端/密钥对。如果要启用它们，则需要创建。

- 最简单的入门方法是禁用所有功能并依赖WorkOS用户名/密码身份验证。为此，请在WorkOS中创建一个用户

1. 导航到身份验证->功能->复制 AuthKit URL .查看图片workos-auth-url.webp
2. 将复制的URL添加给您 config.json 随着 oauth.authorizationServerUrl.开始 https://...

对外曝光

现在，您可以使用隧道工具在外部公开创建的MCP服务器。建议在执行此操作之前设置身份验证（见上文^^），否则它是公开可用的。

吸烟

Ngrok提供隧道服务，您可以使用这些服务将服务器暴露在互联网上

1. 登录/注册 吸烟
2. 按照文档中的说明安装ngrok二进制文件 https://dashboard.ngrok.com/get-started/setup/linux
3. 运行隧道 ngrok http http://localhost:8000
4. 使用URL将服务器注册到LLM客户端 ngrok 给了你+工具的路径。

Pinggy

Pinggy是一种隧道服务，它提供简单的本地主机隧道，使您的本地项目在线，而无需安装客户端。

1. 引导到https://pinggy.io/
2. （可选）注册/登录
3. 运行命令以建立隧道连接 ssh -p 443 -R0:localhost:8000 qr@free.pinggy.io
4. 使用URL将服务器注册到LLM客户端 Pinggy 给了你+工具的路径。

使用AI客户端进行配置

由于此练习的全部目的是将我们的本地MCP服务器安全地暴露在互联网上，让我们将其连接到应用程序。

克劳德·艾（网络）

1. 点击 tuning 聊天框底部的图标->管理连接器
2. 点击 添加自定义连接器
3. 为您的“连接器”命名并添加URL 查看图片claude-connector-setup.webp

• 每个服务器都在自己的端点上公开，因此要使用的URL看起来像 https://gibberish.ngrok-free.app/memento （如果 memento 将是 name 你的命令的价值）。

1. 点击“连接”，进入WorkOS的登录循环 查看图片claude-workos-oauth-login.webp
2. 您应该在右上角看到一个绿色通知，告诉您连接器已连接。

赞助商

该项目由以下机构赞助 Ctxpack -（em-dash）一个用于人工智能工具和工作流程的上下文管理平台。

如果您在整个组织中管理多个MCP服务器或AI工具，Ctxpack可以帮助您将配置打包并共享为可重用的“上下文包”，与Claude、ChatGPT和其他AI平台配合使用。

{人工智能使用的火箭或其他随机表情符号}

了解更多→

______________________________________________________________________

故障排除

端口已在使用中

如果你看到 Error: listen EADDRINUSE :::8000，另一个进程正在使用该端口。

解决：

• 找到并停止冲突过程： lsof -i :8000 （macOS/Linux）或 netstat -ano | findstr :8000 （Windows）
• 使用其他端口： npx @ilities/local-ctx --port 9000

找不到命令错误

如果你看到 Error: spawn XXXX ENOENT，未安装所需的命令。

解决：

• 安装所需的工具（npx、python、uv等）
• 使用可执行文件的完整路径
• 对于npx错误，请确保已安装Node.js： node --version

OAuth令牌验证失败

如果客户端收到401未经授权的错误：

• 验证 authorizationServerUrl 正确且可访问
• 确保OAuth服务器正在运行，并且可以从您的计算机和隧道服务访问
• 检查客户端是否正在发送有效、未过期的JWT令牌
• 对于WorkOS，请验证您的AuthKit URL是否为配置中的最新URL

连接超时

如果客户端报告连接超时：

• 验证本地服务器是否正在运行：检查“侦听端口”日志消息
• 确保隧道服务（ngrok/Pinggy）仍处于活动状态
• 检查防火墙规则是否允许到隧道服务的出站连接
• 验证端点URL包括正确的路径（例如。， /memento 不仅仅是基本URL）

高级用法

多个MCP服务器

通过提供多个命令同时运行多个MCP服务器：

{
  "commands": [
    {
      "name": "memory",
      "command": "npx -y @modelcontextprotocol/server-memory"
    },
    {
      "name": "filesystem",
      "command": "npx -y @modelcontextprotocol/server-filesystem /path/to/directory"
    },
    {
      "name": "github",
      "command": "npx -y @modelcontextprotocol/server-github"
    }
  ],
  "port": 8000
}

每个服务器都可以在自己的端点访问：

• http://localhost:8000/memory
• http://localhost:8000/filesystem
• http://localhost:8000/github

多环境配置

为不同的环境使用单独的配置文件：

config.dev.json：

{
  "commands": [
    {
      "name": "memory",
      "command": "npx -y @modelcontextprotocol/server-memory"
    }
  ],
  "port": 8000
}

config.prod.json：

{
  "commands": [
    {
      "name": "memory",
      "command": "npx -y @modelcontextprotocol/server-memory"
    }
  ],
  "port": 8000,
  "oauth": {
    "authorizationServerUrl": "https://your-workos-instance.workos.com"
  }
}

在环境之间切换：

npx @ilities/local-ctx --config config.dev.json  # Development
npx @ilities/local-ctx --config config.prod.json # Production

程序化使用

虽然设计为CLI工具，但本地ctx可以作为模块导入：

import { LocalContextServer, CommandConfig } from '@ilities/local-ctx';

const commands: CommandConfig[] = [
  {
    name: 'memory',
    command: 'npx -y @modelcontextprotocol/server-memory',
  },
];

const config = {
  commands,
  port: 8000,
};

// Use the server class directly
// Note: This requires the dist build to be available

环境变量参考

安全考虑

未经认证的暴露风险

在没有OAuth身份验证的情况下，切勿将本地ctx暴露到公共互联网。 没有身份验证，任何人都可以：

• 访问计算机上的文件（如果使用文件系统MCP服务器）
• 代表您执行命令
• 通过MCP服务器访问敏感数据

OAuth配置建议

1. 始终为生产部署启用OAuth
2. 使用信誉良好的OAuth提供商 （WorkOS已经过测试）
3. 确保您的OAuth凭据安全 -永远不要将它们提交给版本控制
4. 使用特定于环境的配置 开发与生产

隧道服务安全

使用隧道服务时：

• 更喜欢支持身份验证的服务
• 不使用时定期重新生成隧道URL
• 如果您的OAuth提供商支持，请考虑使用IP分配
• 监控访问日志，防止未经授权的访问尝试

一般最佳实践

• 限制您对外公开的MCP服务器
• 查看MCP服务器可以执行的命令
• 让您的OAuth令牌保持短暂
• 定期更新您的依赖关系

贡献

欢迎投稿！请遵循以下指南：

开发设置

# Clone the repository
git clone https://github.com/Ilities/local-ctx.git
cd local-ctx

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run start

代码风格

此项目使用Prettier进行格式化：

# Check formatting
npm run format:check

# Format code
npm run format

拉取请求流程

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/my-feature
3. 进行更改并确保格式正确
4. 提交一个拉取请求，明确描述更改

报告问题

在报告问题时，请包括：

• 本地ctx的版本（请检查 npm list @ilities/local-ctx)
• 您的操作系统和Node.js版本
• 您正在使用的配置（删除敏感值）
• 完整的错误消息和堆栈跟踪
• 重现问题的步骤

许可证

MIT许可证