Skip to content

README.md

Latest commit

 

History

History
182 lines (149 loc) · 7.99 KB

README.md

File metadata and controls

182 lines (149 loc) · 7.99 KB
Raw

Ariake MCP —— 自定义 Web 请求 MCP

一个可以让模型能够发送高度自定义的网络请求的 MCP(Model Context Protocol)服务器。

功能

  • 自定义 HTTP 方法：GET / POST / PUT / DELETE / OPTIONS / PATCH / HEAD …
  • 自定义请求头：User-Agent、Accept-Encoding、Authorization 等任意头、自定义查询参数
  • 请求体编码：utf-8 / base64 / hex
  • RAW HTTP 请求：通过原始 TCP / TLS 套接字逐字节发送你手写的报文，响应原样返回
  • 自定义返回：text / base64 / hex / hexdump / none
  • 写入到文件：把响应完整写入文件

环境要求

  • Node.js ≥ 20（或 Deno / bun 等运行时）

安装与运行（Node.js / npm）

# 1) 从 npm 安装（全局）
npm install -g ariake-mcp

# 2) 运行
ariake-mcp

# 使用 npx：
npx -y ariake-mcp

接入 MCP 客户端

以 Claude Code 为例（把路径换成本项目绝对路径）：

// 使用 npx
{
  "mcpServers": {
    "ariake": {
      "command": "npx",
      "args": ["-y", "ariake-mcp"]
    }
  }
}

// 使用 `npm install -g ariake-mcp` 全局安装
{
  "mcpServers": {
    "ariake": {
      "command": "ariake-mcp"
    }
  }
}

目录结构

Ariake/
├── deno.json              # 依赖映射、任务、编译/格式化/lint 配置
├── deno.lock              # 依赖锁文件
├── package.json           # npm 包配置(name/bin/exports/files…)
├── build.ts               # 打包脚本(deno bundle → dist/main.js)
├── dist/main.js           # 打包产物:自包含单文件,Node 可直接运行(构建后生成)
├── main.ts                # 入口:创建服务器并连接 stdio 传输层
├── src/
│   ├── deps.ts            # MCP SDK 依赖统一入口(集中处理 Deno 类型解析)
│   ├── runtime.ts         # 运行时适配层(统一用 node: API:套接字/写文件/退出)
│   ├── config.ts          # 服务器元信息(名称、版本)
│   ├── server.ts          # 装配 McpServer
│   ├── http/              # 网络请求的底层实现
│   │   ├── encoding.ts    #   字节↔文本/base64/hex/hexdump、字符集解码、sha256
│   │   ├── raw.ts         #   原始 TCP/TLS 套接字收发
│   │   ├── url.ts         #   从 URL 推断 host/port/tls
│   │   └── result.ts      #   写文件 + 渲染呈现
│   ├── tools/
│   │   ├── mod.ts
│   │   ├── http_request.ts      # 工具：基于 fetch 的自定义 HTTP 请求
│   │   └── raw_http_request.ts  # 工具：RAW HTTP 报文收发
│   ├── resources/
│   │   ├── mod.ts
│   │   ├── info.ts        # 资源 ariake://info：服务器信息
│   │   └── encodings.ts   # 资源 ariake://encodings：支持的编码/模式/字符集
│   └── prompts/
│       ├── mod.ts
│       └── compose_request.ts   # 提示词：起草 RAW HTTP 请求
├── .gitignore
└── README.md

快速开始

deno task start     # 启动(stdio,等待客户端连接)
deno task dev       # 热重载开发
deno task inspect   # 用 MCP Inspector 可视化调试
deno task check     # 类型检查
deno task fmt       # 格式化
deno task lint      # 静态检查

默认权限为 --allow-env --allow-net --allow-write（见下方「权限说明」）。

工具

http_request —— 基于 fetch 的 HTTP(S) 请求

参数 类型 默认 说明
url string — 目标 URL(http/https)，必填
method string GET 任意方法，大小写不敏感
headers object — 自定义请求头（UA、Accept-Encoding 等）
query object — 追加到 URL 的查询参数
body string — 请求体（GET/HEAD 会忽略）
bodyEncoding enum utf-8 utf-8/base64/hex
redirect enum follow follow/manual/error
timeoutMs number 30000 整体超时
outputMode enum text text/base64/hex/hexdump/none
responseEncoding string utf-8 text 模式的字符集
maxInlineBytes number 65536 内联呈现的最大字节，超出截断
outputFile string — 把响应完整字节写入该路径

示例（参数对象）：

{
  "url": "https://httpbin.org/post",
  "method": "POST",
  "headers": { "User-Agent": "ariake-mcp/0.1", "Content-Type": "application/json" },
  "body": "{\"k\":\"v\"}",
  "outputMode": "text"
}

下载二进制并存盘（只看十六进制预览，不内联整段）：

{
  "url": "https://example.com/a.png",
  "outputMode": "hexdump",
  "maxInlineBytes": 256,
  "outputFile": "/tmp/a.png"
}

说明：fetch 会按响应的 Content-Encoding 自动解压，并对少数请求头（如 Host、Content-Length）有保留限制。若要「线缆上的原始字节」或完全控制每个头，请用 raw_http_request。

raw_http_request —— RAW HTTP 报文

参数 类型 默认 说明
raw string — 完整原始报文（请求行+头+空行+体），必填
rawEncoding enum utf-8 utf-8/base64/hex（后两者发送任意二进制）
normalizeLineEndings bool true 仅 utf-8 时：换行统一为 CRLF
url string — 可选：从中推断 host/port/tls
host / port / tls — — 显式指定连接目标（覆盖 url）
connectTimeoutMs number 10000 连接超时
readTimeoutMs number 30000 读取整个响应的总超时
maxBytes number 5000000 读取上限，超出截断
responseTarget enum full 呈现/写入「完整响应」还是「仅响应体」
parse bool true 解析响应行与响应头
outputMode / responseEncoding / maxInlineBytes / outputFile — — 同上，控制响应呈现与落盘

示例：

{
  "url": "https://example.com",
  "raw": "GET / HTTP/1.1\r\nHost: example.com\r\nUser-Agent: ariake-raw\r\nConnection: close\r\n\r\n",
  "outputMode": "text"
}

提示：对 keep-alive 服务器请显式加 Connection: close，否则会一直读到 readTimeoutMs 超时。

资源与提示词

  • 资源 ariake://info：服务器名称、版本与能力清单。
  • 资源 ariake://encodings：列出可用的输入编码、输出模式、文本字符集（由运行时实际校验）。
  • 提示词 compose-raw-request：根据自然语言描述起草一段 HTTP/1.1 原始报文。