{"_id":"@bencibro/postmcp","_rev":"4-c56d80f015ef80252b46fdece9f7da51","name":"@bencibro/postmcp","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"@bencibro/postmcp","version":"1.0.0","keywords":["mcp","model-context-protocol","api-testing","http-client","websocket","graphql","oauth2","assertion","test-automation","ai-agent","claude-desktop","llm-tools"],"license":"MIT","_id":"@bencibro/postmcp@1.0.0","maintainers":[{"name":"bencibro","email":"benci@oksu.club"}],"homepage":"https://github.com/atomgit/postmcp#readme","bugs":{"url":"https://github.com/atomgit/postmcp/issues"},"bin":{"postmcp":"dist/index.js"},"dist":{"shasum":"6283bec766361ef4447d3fb0e57d8181b1549261","tarball":"https://registry.npmjs.org/@bencibro/postmcp/-/postmcp-1.0.0.tgz","fileCount":22,"integrity":"sha512-t8AFiFDU7lHflhU0MuQg23owRiSOvkJKS6pv4JEyPxXC198jAakkTAELKaowU9Ob+jnXAbTQMLc3mlYZrHtNEQ==","signatures":[{"sig":"MEUCIQDw1xM2VuVpPEaLSjsxwail8v6NR7C9X4uDSZ7aJU7fuwIgHH4B2NUFKLkJTmVOEPKNHbZXk3jpfWT7rBYrjnqUMeQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":282931},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"00a23a30a8f7ea807bff71620b880d8ed274a5c5","scripts":{"dev":"tsx src/index.ts","test":"npx tsx src/test/runTests.ts","build":"tsc","start":"node dist/index.js","test:stress":"npx tsx src/test/stressTest.ts","test:negative":"npx tsx src/test/negativeTests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"bencibro","email":"benci@oksu.club"},"repository":{"url":"git+https://github.com/atomgit/postmcp.git","type":"git"},"_npmVersion":"11.12.1","description":"MCP server for AI-driven API testing — HTTP, GraphQL, WebSocket, OAuth2, assertions, chained test suites, and SQLite-persisted history with JSON diff comparison.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.21.0","axios":"^1.18.0","js-yaml":"^4.2.0","sqlite3":"^6.0.1","jsonpath":"^1.3.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","ts-node":"^10.9.2","@types/ws":"^8.18.1","typescript":"^6.0.3","@types/node":"^25.9.3","@types/js-yaml":"^4.0.9","@types/sqlite3":"^3.1.11","@types/jsonpath":"^0.2.4"},"_npmOperationalInternal":{"tmp":"tmp/postmcp_1.0.0_1785681979789_0.859535401237773","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bencibro/postmcp","version":"1.0.1","keywords":["mcp","model-context-protocol","api-testing","http-client","websocket","graphql","oauth2","assertion","test-automation","ai-agent","claude-desktop","llm-tools"],"license":"MIT","_id":"@bencibro/postmcp@1.0.1","maintainers":[{"name":"bencibro","email":"benci@oksu.club"}],"homepage":"https://github.com/atomgit/postmcp#readme","bugs":{"url":"https://github.com/atomgit/postmcp/issues"},"bin":{"postmcp":"dist/index.js"},"dist":{"shasum":"f9704f85b493cbdcdf2f97b13a92ec99f398ef88","tarball":"https://registry.npmjs.org/@bencibro/postmcp/-/postmcp-1.0.1.tgz","fileCount":22,"integrity":"sha512-wRvJwaOcO0SolQvpjylbRwjEouc4HUGyaj6qbbBa9hVdTRlRVPHDILdywWqB2CGynC/AxV32l9S7qKff4Aq6Mw==","signatures":[{"sig":"MEYCIQDc3tGmZVxkgkL3GBd8mvM+qV+jfJ8PvlboZDy/ivs1/wIhALbCW8fqMkuyZcLgauP6JTUnk6egrVwsm91LvQ3tMtCh","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":284642},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"d1c79761f4d9267bcfbe6dd72982de29df5c3b1c","scripts":{"dev":"tsx src/index.ts","test":"npx tsx src/test/runTests.ts","build":"tsc","start":"node dist/index.js","test:stress":"npx tsx src/test/stressTest.ts","test:negative":"npx tsx src/test/negativeTests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"bencibro","email":"benci@oksu.club"},"repository":{"url":"git+https://github.com/atomgit/postmcp.git","type":"git"},"_npmVersion":"11.12.1","description":"MCP server for AI-driven API testing — HTTP, GraphQL, WebSocket, OAuth2, assertions, chained test suites, and SQLite-persisted history with JSON diff comparison.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.21.0","axios":"^1.18.0","js-yaml":"^4.2.0","sqlite3":"^6.0.1","jsonpath":"^1.3.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","ts-node":"^10.9.2","@types/ws":"^8.18.1","typescript":"^6.0.3","@types/node":"^25.9.3","@types/js-yaml":"^4.0.9","@types/sqlite3":"^3.1.11","@types/jsonpath":"^0.2.4"},"_npmOperationalInternal":{"tmp":"tmp/postmcp_1.0.1_1785682511308_0.9273033152738106","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@bencibro/postmcp","version":"1.0.2","keywords":["mcp","model-context-protocol","api-testing","http-client","websocket","graphql","oauth2","assertion","test-automation","ai-agent","claude-desktop","llm-tools"],"license":"MIT","_id":"@bencibro/postmcp@1.0.2","maintainers":[{"name":"bencibro","email":"benci@oksu.club"}],"homepage":"https://github.com/atomgit/postmcp#readme","bugs":{"url":"https://github.com/atomgit/postmcp/issues"},"bin":{"postmcp":"dist/index.js"},"dist":{"shasum":"a3534cec6f3b5d5e02c6a9098c957691f7517bda","tarball":"https://registry.npmjs.org/@bencibro/postmcp/-/postmcp-1.0.2.tgz","fileCount":22,"integrity":"sha512-eWHh7xfKIvHpUHseTON5nvuzcyRUegAYByxYtCXZoZYmTxdMOAa58iYCO53lXAod5kSPKaM8yuORylKyGZvOIg==","signatures":[{"sig":"MEYCIQD589cL4U00TBq1eVktz5aVbMUUEKRmc6GUxE+tqLbgOwIhAJ73FfYayOCp2LLUCRewFBtHdBQHAOGfW+juJDs3YU1P","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":285301},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"5f82e237e92419f11f85f6e2c848cc078e557bac","scripts":{"dev":"tsx src/index.ts","test":"npx tsx src/test/runTests.ts","build":"tsc","start":"node dist/index.js","test:stress":"npx tsx src/test/stressTest.ts","test:negative":"npx tsx src/test/negativeTests.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"bencibro","email":"benci@oksu.club"},"repository":{"url":"git+https://github.com/atomgit/postmcp.git","type":"git"},"_npmVersion":"11.12.1","description":"MCP server for AI-driven API testing — HTTP, GraphQL, WebSocket, OAuth2, assertions, chained test suites, and SQLite-persisted history with JSON diff comparison.","directories":{},"_nodeVersion":"25.9.0","dependencies":{"ws":"^8.21.0","axios":"^1.18.0","js-yaml":"^4.2.0","sqlite3":"^6.0.1","jsonpath":"^1.3.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.22.4","ts-node":"^10.9.2","@types/ws":"^8.18.1","typescript":"^6.0.3","@types/node":"^25.9.3","@types/js-yaml":"^4.0.9","@types/sqlite3":"^3.1.11","@types/jsonpath":"^0.2.4"},"_npmOperationalInternal":{"tmp":"tmp/postmcp_1.0.2_1785682678260_0.5943382657120442","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@bencibro/postmcp","version":"1.0.3","description":"MCP server for AI-driven API testing — HTTP, GraphQL, WebSocket, OAuth2, assertions, chained test suites, and SQLite-persisted history with JSON diff comparison.","main":"dist/index.js","bin":{"postmcp":"dist/index.js"},"type":"module","engines":{"node":">=18.0.0"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/atomgit/postmcp.git"},"keywords":["mcp","model-context-protocol","api-testing","http-client","websocket","graphql","oauth2","assertion","test-automation","ai-agent","claude-desktop","llm-tools"],"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsx src/index.ts","test":"npx tsx src/test/runTests.ts","test:negative":"npx tsx src/test/negativeTests.ts","test:stress":"npx tsx src/test/stressTest.ts","prepublishOnly":"npm run build && npm test"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","axios":"^1.18.0","js-yaml":"^4.2.0","jsonpath":"^1.3.0","sqlite3":"^6.0.1","ws":"^8.21.0"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/jsonpath":"^0.2.4","@types/node":"^25.9.3","@types/sqlite3":"^3.1.11","@types/ws":"^8.18.1","ts-node":"^10.9.2","tsx":"^4.22.4","typescript":"^6.0.3"},"gitHead":"22651d3c58efe2dd7769746185edd22ffc57e19e","_id":"@bencibro/postmcp@1.0.3","bugs":{"url":"https://github.com/atomgit/postmcp/issues"},"homepage":"https://github.com/atomgit/postmcp#readme","_nodeVersion":"24.18.1","_npmVersion":"11.16.0","dist":{"integrity":"sha512-FSS5xrMtHDQi9eQPcDqQ7BbxHRZS86N2GDrd4nzJcHigIGLwyy5nHVauPZtvWniWjlxk1lgplFhNLB3AS78YpA==","shasum":"4cd0d839aa28187b602e2fc21ec5b53eac40b85a","tarball":"https://registry.npmjs.org/@bencibro/postmcp/-/postmcp-1.0.3.tgz","fileCount":22,"unpackedSize":289745,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFyLXUZN5EN2B9N9qXECoOyjs55kw48ilwHfzBTUa3atAiBTng/0FTTxrszwt8VEa5WGjzhKrdOmga3NxjJ/FVFtag=="}]},"_npmUser":{"name":"bencibro","email":"benci@oksu.club"},"directories":{},"maintainers":[{"name":"bencibro","email":"benci@oksu.club"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/postmcp_1.0.3_1786091922389_0.23181588438646417"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-02T14:46:19.591Z","modified":"2026-08-07T08:38:42.761Z","1.0.0":"2026-08-02T14:46:19.925Z","1.0.1":"2026-08-02T14:55:11.465Z","1.0.2":"2026-08-02T14:57:58.397Z","1.0.3":"2026-08-07T08:38:42.530Z"},"bugs":{"url":"https://github.com/atomgit/postmcp/issues"},"license":"MIT","homepage":"https://github.com/atomgit/postmcp#readme","keywords":["mcp","model-context-protocol","api-testing","http-client","websocket","graphql","oauth2","assertion","test-automation","ai-agent","claude-desktop","llm-tools"],"repository":{"type":"git","url":"git+https://github.com/atomgit/postmcp.git"},"description":"MCP server for AI-driven API testing — HTTP, GraphQL, WebSocket, OAuth2, assertions, chained test suites, and SQLite-persisted history with JSON diff comparison.","maintainers":[{"name":"bencibro","email":"benci@oksu.club"}],"readme":"# postmcp 🚀 - API Request & Automation Testing MCP Server\n\n[English](#english) | [中文说明](#中文说明)\n\n---\n\n## English\n\nA high-performance Model Context Protocol (MCP) server written in Node.js (TypeScript) designed for API request automation and automated testing. It features a unified local SQLite database storage allowing LLM agents to manage projects, configure environment variables and credential tokens, run REST and WebSocket requests, evaluate assertions, and audit execution histories.\n\n### ✨ Features\n\n- **🗄️ SQLite Unified Storage**: Consolidates projects, profiles, variables, cache tokens, history logs, and test suites into `~/.postmcp/postmcp.db` under user-only file permissions (`0600`).\n- **📁 Multi-Project Workspaces**: Easily partition different API workspaces (e.g. e-commerce-api, auth-service).\n- **⚙️ Environment Profiles**: Configure separate environments (e.g. `dev`, `prod`, `local`) with specific base URLs (supports `{{var}}` interpolation), headers, cookies, authentication methods, and default timeout.\n- **🔐 Automatic OAuth2 Flow & Token Injection**: Full Support for Bearer Tokens, API Keys, and automated OAuth2 **Client Credentials** and **Password** grants with expiration caching.\n- **📥 WebSocket persistent connection pool**: Persistent socket clients with message buffering, and regex patterns wait features (block and wait for expected responses).\n- **⏱️ Assertion Engine & Diff Engine**: Evaluates request status codes, times, response headers, and JSONPath body expressions. Easily generates Markdown structural differences comparing two requests (supports `table` and `unified` diff formats).\n- **📊 Chaining Test Suite Runner**: Executes multi-step API scenarios, automatically extracting dynamic variables (e.g. dynamic IDs, authorization tokens) and injecting them into subsequent steps.\n- **🧪 GraphQL Support**: Dedicated `graphql_request` tool for sending GraphQL queries/mutations with variable injection.\n- **📁 File Upload Support**: Upload files via `form-data` body type using `fileFields` parameter.\n- **💾 Test Suite Persistence**: Save, load, list, and delete test suites in the database for reuse.\n- **📤 Import/Export Ecosystem**: Import Postman Collections, export/import environments and projects as portable JSON.\n- **📖 Swagger/OpenAPI Import (Enhanced)**: Now includes response status codes and response body schemas in generated Markdown.\n- **🔍 Advanced History Filtering**: Filter audit logs by method, status code, URL keyword, and date range.\n- **📋 History Export**: Export audit logs as JSON for external analysis.\n- **🛡️ Outbound & File Safety**: Outbound HTTP, WebSocket, OAuth2, and Swagger URLs require an explicit allowlist and are checked against DNS-resolved private/reserved addresses. Local file reads are sandboxed, size-limited, and require explicit confirmation.\n- **🔒 Secret Protection**: Credentials are masked in environment listings, variables, exports, and request history. Secret reads/exports and destructive operations require explicit confirmation.\n\n### 🛠️ Setup & Build\n\nPublished package: [`@bencibro/postmcp`](https://www.npmjs.com/package/@bencibro/postmcp).\n\nFor the published package, install the MCP server globally:\n\n```bash\nnpm install -g @bencibro/postmcp\npostmcp\n```\n\nOr run it without a global install:\n\n```bash\nnpm install @bencibro/postmcp\nnpx -y @bencibro/postmcp\n```\n\nThe local install form is useful when the MCP client configuration runs from a project directory. The package exposes the `postmcp` executable through its `bin` entry.\n\nTo develop from this repository instead:\n\n1. Install dependencies:\n   ```bash\n   npm install\n   ```\n2. Compile TypeScript:\n   ```bash\n   npm run build\n   ```\n\nBefore sending any outbound request, configure an explicit allowlist with `env_set_allowlist`. An empty list denies all outbound requests. For trusted local services, use the explicit `private:` form, for example:\n\n```json\n{ \"domains\": [\"api.example.com\", \"private:localhost\"] }\n```\n\nLocal file tools (`fileFields`, `test_run_suite.dataSource`, `swagger_import.filePath`, and `postman_import`) require `confirmFileAccess: true`. Files must be inside `POSTMCP_FILE_ROOTS` (defaults to the project directory), cannot be protected credential files, and are limited to 10 MiB by default. Set `POSTMCP_MAX_FILE_BYTES` to adjust the limit up to 100 MiB.\n\n### 🚀 First MCP Workflow\n\nAfter connecting an MCP client, run these tools in order:\n\n```text\nproject_create       { \"name\": \"My API\" }\nenv_configure        { \"name\": \"dev\", \"baseUrl\": \"https://api.example.com\" }\nenv_set_allowlist    { \"domains\": [\"api.example.com\"] }\nhttp_request         { \"url\": \"/health\", \"method\": \"GET\", \"returnBody\": false }\nhistory_list         { \"limit\": 5 }\n```\n\nThe allowlist step is required. An empty allowlist denies all outbound requests.\n\n### ⚙️ Integrate with Claude Desktop\n\nAdd this configuration to your Claude Desktop config (usually at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n  \"mcpServers\": {\n    \"postmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bencibro/postmcp\"]\n    }\n  }\n}\n```\n\n### 📖 MCP Tool Guide\n\n1. **Guide & Instructions**: `mcp_usage_guide` (dynamically returns workflow guidelines on variables, chaining, and socket testing).\n2. **Projects (`project_*`)**: `project_create`, `project_switch`, `project_list`, `project_delete` (requires `expectedProjectName` and `confirm: true`), `project_rename`.\n3. **Environments (`env_*`)**: `env_configure` (with `timeout`, `oauth2Config` password grant), `env_switch`, `env_list`, `env_delete` (requires `expectedEnvironmentName` and `confirm: true`), `env_rename`, `env_set_variable`, `env_get_variable` (use `includeSecret` + `confirmSecret: true` to reveal a sensitive value), `env_delete_variable`, `env_list_variables` (use `includeSecrets` + `confirmSecrets: true` to reveal sensitive values), `env_set_allowlist`, `env_get_allowlist`.\n4. **HTTP Requests**: `http_request` (REST requests with file upload via `fileFields` and any HTTP method), `graphql_request` (dedicated GraphQL query tool), `test_run_suite` (sequential scenario runner; local `dataSource` files require `confirmFileAccess: true`).\n5. **WebSocket Client (`ws_*`)**: `ws_connect`, `ws_send`, `ws_read` (regex waiting support), `ws_close`, `ws_list`.\n6. **Test Suite Persistence (`suite_*`)**: `suite_save`, `suite_load`, `suite_list`, `suite_delete` (requires `expectedSuiteName` and `confirm: true`; suites are isolated to the active project).\n7. **Request History (`history_*`)**: `history_list` (with advanced filters: method, statusCode, urlKeyword, dateFrom, dateTo), `history_get` (detail log), `history_compare` (diff logs, supports `table` and `unified` format), `history_clear` (requires `confirm: true`), `history_export`.\n8. **Database Maintenance (`db_*`)**: `db_status` (returns database file path, file size in KB, and table row counts), `db_reset` (factory reset DB, requires `confirm: true`).\n9. **Swagger Import (`swagger_import`)**: `swagger_import` (imports routes and schemas from JSON/YAML files or URLs into Markdown references; now includes response status codes and schemas).\n10. **Import/Export**: `postman_import` (Postman Collection v2; requires `confirmFileAccess: true`), `env_export`, `env_import`, `project_export`, `project_import`. Exports mask secrets by default; use `includeSecrets: true` together with `confirmSecrets: true` only when needed.\n\n### 🧪 Integration Tests\n\n```bash\nnpx tsx src/test/runTests.ts\nnpm run test:negative\nnpm run test:stress\n```\n\n### 📚 Additional Documentation\n\n- [`ai_instructions.md`](./ai_instructions.md): Full tool reference and recommended agent workflows.\n- [`walkthrough.md`](./walkthrough.md): Architecture and end-to-end walkthrough.\n- [`postmcp_vs_postman.md`](./postmcp_vs_postman.md): Feature comparison and current gaps.\n- [`ROADMAP_v2.0.md`](./ROADMAP_v2.0.md): Planned future capabilities.\n\n---\n\n## 中文说明\n\n**postmcp** 是使用 Node.js (TypeScript) 编写的高性能 Model Context Protocol (MCP) 服务，专为 API 接口自动化请求与集成测试设计。采用统一的本地 SQLite 数据库作为存储，支持多项目切换、多环境配置（如 dev, prod）、OAuth2 认证缓存，以及详尽的请求历史审计与响应对比（Diff）功能。\n\n### ✨ 功能特性\n\n- **🗄️ SQLite 统一存储**：将项目、环境、变量、缓存 token、请求日志和测试套件集中持久化到 `~/.postmcp/postmcp.db`，使用 Unix 用户独占权限 (`0600`) 保护。\n- **📁 多项目工作区**：支持创建和隔离多个独立的 API 测试项目（例如 `PaymentGateway`、`UserAuth`）。\n- **⚙️ 环境配置文件**：每个项目下可配置多个环境（如 `dev`、`prod`、`local`），每个环境可包含不同的 Base URL（支持 `{{var}}` 插值）、变量池、默认 Headers、Cookies、鉴权配置及默认超时时间。\n- **🔐 OAuth2 自动换单与 Token 注入**：支持 Bearer Token、API Key，以及 OAuth2 **Client Credentials** 和 **Password** 模式的自动获取、过期校验与缓存。\n- **📥 WebSocket 状态连接池**：维护持久化的 socket 连接，支持发送/接收消息，并支持基于正则的 `waitForPattern` 异步阻塞监听。\n- **⏱️ 断言与差异对比引擎**：提供多类型断言验证（状态码、响应时间、Header、JSONPath 表达式），并能对比两个请求记录的响应差异（支持 `table` 和 `unified` 两种 diff 格式）。\n- **📊 串联测试用例运行器 (Test Suite)**：按顺序执行多步 API 请求，支持通过 JSONPath 提取响应参数，并自动注入到后续请求中。\n- **🧪 GraphQL 支持**：专用 `graphql_request` 工具发送 GraphQL 查询/变更，自动拼接 body。\n- **📁 文件上传支持**：通过 `fileFields` 参数在 form-data 中上传本地文件。\n- **💾 测试套件持久化**：在数据库中保存、加载、列举和删除测试套件。\n- **📤 导入导出生态**：导入 Postman Collection，导出/导入环境和项目的可移植 JSON。\n- **📖 Swagger/OpenAPI 导入（增强）**：现在包含响应状态码和响应体 Schema。\n- **🔍 高级历史过滤**：按请求方法、状态码、URL 关键词、时间范围过滤审计日志。\n- **📋 历史导出**：将审计日志导出为 JSON 用于外部分析。\n- **🛡️ 出站与文件安全**：HTTP、WebSocket、OAuth2 和 Swagger 远程 URL 必须先加入显式白名单，并会校验 DNS 解析结果是否指向私网或保留地址。本地文件读取受目录沙箱、大小限制和显式确认保护。\n- **🔒 敏感信息保护**：环境列表、变量查询、导出数据和请求历史默认脱敏；读取秘密和执行破坏性操作都需要显式确认。\n\n### 🛠️ 安装与编译\n\n已发布 npm 包：[ `@bencibro/postmcp`](https://www.npmjs.com/package/@bencibro/postmcp)。\n\n发布版安装：\n\n```bash\nnpm install -g @bencibro/postmcp\npostmcp\n```\n\n也可以不全局安装，直接运行：\n\n```bash\nnpm install @bencibro/postmcp\nnpx -y @bencibro/postmcp\n```\n\n在项目目录中本地安装后，也可以在 MCP 客户端配置中使用 `npx -y @bencibro/postmcp` 启动。该包通过 `bin` 字段提供 `postmcp` 命令。\n\n如果需要从源码开发：\n\n1. 安装依赖包：\n   ```bash\n   npm install\n   ```\n2. 编译 TypeScript：\n   ```bash\n   npm run build\n   ```\n\n发送任何出站请求前，请先使用 `env_set_allowlist` 配置明确的域名白名单。空白名单会拒绝所有出站请求。访问可信本地服务时，必须明确使用 `private:` 前缀，例如：\n\n```json\n{ \"domains\": [\"api.example.com\", \"private:localhost\"] }\n```\n\n本地文件工具（`fileFields`、`test_run_suite.dataSource`、`swagger_import.filePath`、`postman_import`）必须传入 `confirmFileAccess: true`。文件必须位于 `POSTMCP_FILE_ROOTS`（默认是项目目录）内，受保护的凭据文件会被拒绝，默认大小上限为 10 MiB。可通过 `POSTMCP_MAX_FILE_BYTES` 调整，上限为 100 MiB。\n\n### 🚀 首次使用流程\n\n连接 MCP 客户端后，按以下顺序调用工具：\n\n```text\nproject_create       { \"name\": \"My API\" }\nenv_configure        { \"name\": \"dev\", \"baseUrl\": \"https://api.example.com\" }\nenv_set_allowlist    { \"domains\": [\"api.example.com\"] }\nhttp_request         { \"url\": \"/health\", \"method\": \"GET\", \"returnBody\": false }\nhistory_list         { \"limit\": 5 }\n```\n\n白名单配置是必需步骤。空白名单会拒绝所有出站请求。\n\n### ⚙️ 对接 Claude 桌面客户端\n\n在您的 Claude Desktop 配置文件中（通常位于 macOS 的 `~/Library/Application Support/Claude/claude_desktop_config.json`），添加以下配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"postmcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@bencibro/postmcp\"]\n    }\n  }\n}\n```\n\n### 📖 MCP 工具接口使用指南\n\n1. **帮助与指南 (`mcp_usage_guide`)**：\n   - `mcp_usage_guide`：让 AI 助手直接获取关于变量插值、串联测试、WebSocket 异步监听等的高级使用说明。\n2. **项目管理 (`project_*`)**：\n   - `project_create`：创建一个新的项目测试空间。\n   - `project_switch`：切换当前活动的项目空间。\n   - `project_list`：列出所有项目。\n   - `project_delete`：删除指定项目（级联删除关联的环境及历史记录），必须提供准确的 `expectedProjectName` 和 `confirm: true`。\n   - `project_rename`：重命名项目。\n3. **环境配置 (`env_*`)**：\n   - `env_configure`：在活动项目下创建或修改环境（支持 timeout、oauth2Config password grant）。\n   - `env_switch`：切换活动环境。\n   - `env_list`：列出当前项目下的环境列表（敏感 Token 会自动脱敏遮蔽）。\n   - `env_delete`：删除环境配置文件，必须提供准确的 `expectedEnvironmentName` 和 `confirm: true`。\n   - `env_rename`：重命名环境。\n   - `env_set_variable`：往当前活动环境写入自定义变量，在请求中通过 `{{variableName}}` 引用。\n   - `env_get_variable`：查询指定变量的值；敏感变量需要 `includeSecret: true` 和 `confirmSecret: true` 才会返回原值。\n   - `env_delete_variable`：删除指定变量。\n   - `env_list_variables`：列出所有环境变量；敏感值默认脱敏，必须同时提供 `includeSecrets: true` 和 `confirmSecrets: true` 才会返回原值。\n   - `env_set_allowlist`：设置安全出站域名白名单。\n   - `env_get_allowlist`：查询当前白名单配置。\n4. **HTTP 接口请求**：\n   - `http_request`：发送单次 API 请求，支持文件上传 (`fileFields`) 和任意 HTTP 方法；文件上传需要 `confirmFileAccess: true`。\n   - `graphql_request`：发送 GraphQL 查询/变更。\n   - `test_run_suite`：执行串联式多步 API 测试场景，支持变量提取与传递。\n5. **WebSocket 客户端 (`ws_*`)**：\n   - `ws_connect`：发起 WebSocket 连接，维持长连接状态。\n   - `ws_send`：发送文本或 JSON 数据帧。\n   - `ws_read`：读取已收到的消息缓存，支持传入 `waitForPattern` 正则阻塞等待响应。\n   - `ws_close`：关闭 WebSocket 连接。\n   - `ws_list`：列出当前所有活跃的 socket 连接 ID。\n6. **测试套件持久化 (`suite_*`)**：\n   - `suite_save`：保存测试套件到数据库。\n   - `suite_load`：加载并运行已保存的测试套件。\n   - `suite_list`：列出已保存的测试套件。\n   - `suite_delete`：删除已保存的测试套件，必须提供准确的 `expectedSuiteName` 和 `confirm: true`。\n7. **历史日志与响应对比 (`history_*`)**：\n   - `history_list`：分页查询历史记录（支持 method、statusCode、urlKeyword、dateFrom、dateTo 高级过滤）。\n   - `history_get`：根据 ID 检索单次请求响应的详细报文。\n   - `history_compare`：对两个历史请求进行多维度比对（支持 `table` 和 `unified` 两种格式）。\n   - `history_clear`：清理历史审计记录，必须提供 `confirm: true`。\n   - `history_export`：导出历史记录为 JSON。\n8. **数据库维护 (`db_*`)**：\n   - `db_status`：查询本地 SQLite 数据库的文件路径、大小（KB）及各个表的数据量。\n   - `db_reset`：**危险操作**：重置数据库（需要 `confirm: true` 确认）。\n9. **Swagger 导入 (`swagger_import`)**：\n   - `swagger_import`：读取本地或远程 Swagger/OpenAPI 文件，生成结构化 Markdown 文档（含响应状态码和 Schema）。\n10. **导入/导出**：\n    - `postman_import`：导入 Postman Collection v2 文件（需要 `confirmFileAccess: true`）。\n    - `env_export` / `env_import`：导出/导入环境配置 JSON；导出默认脱敏，导出秘密需要 `includeSecrets: true` 和 `confirmSecrets: true`。\n    - `project_export` / `project_import`：导出/导入项目（含所有环境）JSON；导出默认脱敏，导出秘密需要 `includeSecrets: true` 和 `confirmSecrets: true`。\n\n### 🧪 本地集成测试\n\n您可以启动内置的 Mock 服务器并对所有功能模块进行全自动回归测试：\n\n```bash\nnpx tsx src/test/runTests.ts\nnpm run test:negative\nnpm run test:stress\n```\n","readmeFilename":"README.md"}