convez.ai
MCP Server
guangda88

Ling-term-mcp

guangda88/Ling-term-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

灵犀 (LingTermMCP) — MCP终端服务器 | MCP terminal server for AI command execution

Instalação

$npx convez-ai guangda88/Ling-term-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
v1.0.0
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

Ling-term-mcp(灵犀)

让 AI 助手精准操控终端的 MCP 服务器


项目简介

Ling-term-mcp(灵犀) 是一个基于 MCP(Model Context Protocol)标准的终端操作服务器,让 Claude、Cursor、Copilot 等 AI 助手能够安全、高效地执行终端命令和管理会话。

核心特性

  • MCP 原生: 完全兼容 MCP 标准,无缝对接主流 AI 助手
  • 双模式执行: execFile 直接执行 + shell 模式支持管道、链式命令、内置命令
  • 安全优先: 命令黑名单、危险模式检测、环境变量过滤、Shell 注入防护
  • 会话管理: 多会话并发、持久化、工作目录追踪、环境变量继承、命令历史
  • 决策溯源: 完整的决策记录链,追踪推理、预期结果和实际结果
  • 行为契约: 检测危险行为模式,如敏感文件读取后的网络命令
  • 会话快照: 会话结束时生成完整的行为摘要和审计轨迹
  • 元认知审计: 评估 AI 决策质量,检测推理偏差和模式异常
  • 性能监控: 内置 PerformanceMonitor,实时追踪 P50/P95/P99 指标
  • 高覆盖测试: 263 个测试,17 个测试套件,全部通过

快速开始

安装

git clone https://github.com/guangda/ling-term-mcp.git
cd ling-term-mcp
npm install

启动

npm run dev        # 开发模式(tsx,无需构建)
npm run build      # 编译 TypeScript
npm start          # 生产模式

连接到 AI 助手

Cursor

{
  "mcpServers": {
    "ling-term-mcp": {
      "command": "npx",
      "args": ["-y", "ling-term-mcp"]
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中添加:

{
  "mcpServers": {
    "ling-term-mcp": {
      "command": "npx",
      "args": ["-y", "ling-term-mcp"]
    }
  }
}

Crush CLI

在 ~/.config/crush/crush.json 的 mcp 中添加:

"ling-term-mcp": {
  "command": "node",
  "args": ["/path/to/ling-term-mcp/dist/cli.js"]
}

可用工具

1. execute_command — 执行终端命令

参数类型必填说明
commandstring是命令名称(非 shell)或完整命令字符串(shell 模式)
argsstring[]否命令参数(仅非 shell 模式使用)
session_idstring否会话 ID,绑定工作目录和环境
shellboolean否true 使用 /bin/sh -c 执行,支持管道、&&、cd、export 等
timeoutnumber否超时毫秒数,默认 60000,最大 600000

非 shell 模式(默认):使用 execFile,参数独立传递,无 shell 解析风险:

{
  "command": "echo",
  "args": ["Hello, World!"],
  "session_id": "my-session"
}

Shell 模式:使用 exec,支持完整 shell 语法:

{
  "command": "cd /var && ls -la | head -10",
  "shell": true,
  "session_id": "my-session"
}

Shell 模式下,cd 会自动更新会话工作目录,export 会更新会话环境变量。

2. create_session — 创建会话

参数类型必填说明
namestring否会话名称
working_directorystring否工作目录,默认 process.cwd()

3. destroy_session — 销毁会话

参数类型必填说明
session_idstring是要销毁的会话 ID

4. list_sessions — 列出会话

无参数,返回所有活跃会话列表。

5. sync_terminal — 同步终端状态

参数类型必填说明
session_idstring是会话 ID

返回:工作目录、会话环境变量、命令历史、平台信息、时间戳。


项目结构

Ling-term-mcp/
├── src/
│   ├── index.ts              # MCP Server 入口
│   ├── cli.ts                # CLI 入口
│   ├── tools/                # MCP 工具
│   │   ├── execute_command.ts
│   │   ├── create_session.ts
│   │   ├── destroy_session.ts
│   │   ├── list_sessions.ts
│   │   └── sync_terminal.ts
│   ├── sessions/
│   │   └── store.ts          # 会话持久化(JSON 文件)
│   ├── security/
│   │   └── validator.ts      # 安全验证器
│   └── monitoring/
│       └── performance.ts    # 性能监控
├── tests/
│   ├── unit/                 # Jest 单元测试
│   ├── e2e/                  # Node.js E2E 测试
│   └── stress/               # 压力测试
├── docs/
│   ├── API.md
│   └── USER_GUIDE.md
└── .lingflow/                # lingflow 工作流

安全

安全架构

| 层级 | 机制 | 说明 | | ---------- | ------------------------------- | ------------------------------------ | -------- | | 命令长度 | maxCommandLength: 10000 | 超长命令直接拒绝 | | 黑名单 | rm, sudo, kill, dd, shutdown... | 始终生效 | | 白名单 | ls, git, npm, node, python... | allowUnknownCommands: false 时启用 | | 危险模式 | rm -rf /, fork bomb, curl | bash... | 正则检测 | | Shell 注入 | ;, 反引号, $(...) | 非 shell 模式参数检测 | | 环境过滤 | SECRET/TOKEN/PASSWORD 关键字 | 阻止敏感变量传递给子进程 | | 输出截断 | 10000 字符 | 防止内存溢出 |

双模式安全策略

  • 非 shell 模式(默认):execFile 参数化执行,参数经过 shell 注入检测
  • Shell 模式(shell: true):允许 &&、|、$ 等 shell 语法,但黑名单命令、危险模式、管道攻击仍被拦截

默认黑名单

rm, rmdir, sudo, su, kill, killall, pkill, dd, mkfs, fdisk,
shutdown, reboot, halt, chmod, chown, passwd, systemctl, ...

Shell 解释器(bash, sh, zsh, fish)和网络工具(curl, wget)已从白名单移除。解释器 RCE flag(node -e、python -c)被单独拦截,curl|bash 等管道攻击也会被危险模式检测拦截。


测试

npm test              # 单元测试(263 tests,17 suites)
npm run test:coverage # 覆盖率报告
npm run test:e2e      # E2E 测试(Node.js test runner)
npm run test:stress   # 压力测试
指标覆盖率
Statements87%
Branches72%
Functions83%
Lines87%

开发

npm run dev          # 开发模式
npm run dev:watch    # 开发 + watch
npm run build        # 编译
npm run lint         # 代码检查
npm run format       # 代码格式化
npm run clean        # 清理构建产物

添加新工具

  1. 创建 src/tools/my_tool.ts(definition + handler)
  2. 在 src/index.ts 注册 definition 和 handler
  3. 创建 tests/unit/my_tool.test.ts
  4. npm run lint && npx tsc --noEmit && npm test

技术栈

依赖版本用途
TypeScript5.4+类型安全
Node.js>=18.0运行时
@modelcontextprotocol/sdk^1.27.1MCP 协议
Jest29测试框架
ESLint + Prettier-代码质量

贡献

  1. Fork → 创建分支 → 开发 → 测试 → PR
  2. 确保 npm run lint && npx tsc --noEmit && npm test 全部通过

许可证

MIT License


Ling-term-mcp(灵犀)- 心有灵犀一点通,AI 精准操控终端

版本: 1.1.0 基于: lingminopt + lingflow

Ver o original no GitHub

Bom para

Relacionados