{"_id":"@1587causalai/configurable-personal-fs-server","_rev":"2-104f03ed12a1c2a7a280f5d5e589b08f","name":"@1587causalai/configurable-personal-fs-server","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@1587causalai/configurable-personal-fs-server","version":"0.1.0","keywords":["mcp","model-context-protocol","ai","personal-documents","filesystem","configurable-server"],"author":{"name":"1587causalai"},"license":"MIT","_id":"@1587causalai/configurable-personal-fs-server@0.1.0","maintainers":[{"name":"1587causalai","email":"zj3712@gmail.com"}],"homepage":"https://github.com/1587causalai/servers/tree/main/src/filesystem#readme","bugs":{"url":"https://github.com/1587causalai/servers/issues"},"bin":{"configurable-personal-fs-server":"dist/index.js"},"dist":{"shasum":"4d936370e6e65366ab85ff2662dba7d75eefa7c1","tarball":"https://registry.npmjs.org/@1587causalai/configurable-personal-fs-server/-/configurable-personal-fs-server-0.1.0.tgz","fileCount":3,"integrity":"sha512-wKHNj80sovbwcyDFsBEbTaq9Mac8NIfvjgXQKaj+ucFnyFJGoTl9fza+hxGLuBkGEO7LJipt/eaiSgkDLFKXLw==","signatures":[{"sig":"MEYCIQCAH2z4V24QmOJQ+AEbYajRce8JxGB7h7fBc9g46w9vWwIhAMxjxnKBJ+eMjZC2ODtOoY6OUThBPVbIfyQpk1eJvmgk","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31324},"type":"module","gitHead":"9e26bb639737d67c675bb90012bbf936ca7b4e8f","scripts":{"build":"tsc && shx chmod +x dist/*.js","watch":"tsc --watch","prepare":"npm run build"},"_npmUser":{"name":"1587causalai","email":"zj3712@gmail.com"},"repository":{"url":"git+https://github.com/1587causalai/servers.git","type":"git","directory":"src/filesystem"},"_npmVersion":"10.9.2","description":"一个高度可配置的个人文件系统MCP服务器，具有上下文感知AI交互能力。允许通过命令行参数动态配置根目录，或默认为当前工作目录。","directories":{},"_nodeVersion":"23.11.0","dependencies":{"diff":"^5.1.0","glob":"^10.3.10","minimatch":"^10.0.1","zod-to-json-schema":"^3.23.5","@modelcontextprotocol/sdk":"0.5.0"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","typescript":"^5.3.3","@types/diff":"^5.0.9","@types/node":"^22","@types/minimatch":"^5.1.2"},"_npmOperationalInternal":{"tmp":"tmp/configurable-personal-fs-server_0.1.0_1747546535143_0.8040524247021474","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@1587causalai/configurable-personal-fs-server","version":"0.1.1","description":"一个高度可配置的个人文件系统MCP服务器，具有上下文感知AI交互能力。允许通过命令行参数动态配置根目录，或默认为当前工作目录。","license":"MIT","author":{"name":"1587causalai"},"homepage":"https://github.com/1587causalai/servers/tree/main/src/filesystem#readme","bugs":{"url":"https://github.com/1587causalai/servers/issues"},"repository":{"type":"git","url":"git+https://github.com/1587causalai/servers.git","directory":"src/filesystem"},"keywords":["mcp","model-context-protocol","ai","personal-documents","filesystem","configurable-server"],"type":"module","bin":{"configurable-personal-fs-server":"dist/index.js"},"scripts":{"build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","watch":"tsc --watch"},"dependencies":{"@modelcontextprotocol/sdk":"0.5.0","diff":"^5.1.0","glob":"^10.3.10","minimatch":"^10.0.1","zod-to-json-schema":"^3.23.5"},"devDependencies":{"@types/diff":"^5.0.9","@types/minimatch":"^5.1.2","@types/node":"^22","shx":"^0.3.4","typescript":"^5.3.3"},"_id":"@1587causalai/configurable-personal-fs-server@0.1.1","gitHead":"9e26bb639737d67c675bb90012bbf936ca7b4e8f","_nodeVersion":"23.11.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-g4hPWPYD0MOVK8Fe/bMFO5PUvi686qi9vxgLoUygbaIR3X8J+X3esDZwUWb+Tvy1XiHMQgrnD0NFsk+lMDfN8g==","shasum":"a6ab33da5bdc8f4e5d5014cc87371307a65cbebc","tarball":"https://registry.npmjs.org/@1587causalai/configurable-personal-fs-server/-/configurable-personal-fs-server-0.1.1.tgz","fileCount":3,"unpackedSize":30965,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCQhgKyk4n1Qhk8TK7qu/WgnhAsSBDp/6Hw4Zis+pwJLwIhAPe4PF3SX0mKScEgzqnVoFmaQyCs9++dVfcG7lCCupKc"}]},"_npmUser":{"name":"1587causalai","email":"zj3712@gmail.com"},"directories":{},"maintainers":[{"name":"1587causalai","email":"zj3712@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/configurable-personal-fs-server_0.1.1_1747549011978_0.2861875635024742"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-18T05:35:35.064Z","modified":"2025-05-18T06:16:52.674Z","0.1.0":"2025-05-18T05:35:35.573Z","0.1.1":"2025-05-18T06:16:52.188Z"},"bugs":{"url":"https://github.com/1587causalai/servers/issues"},"author":{"name":"1587causalai"},"license":"MIT","homepage":"https://github.com/1587causalai/servers/tree/main/src/filesystem#readme","keywords":["mcp","model-context-protocol","ai","personal-documents","filesystem","configurable-server"],"repository":{"type":"git","url":"git+https://github.com/1587causalai/servers.git","directory":"src/filesystem"},"description":"一个高度可配置的个人文件系统MCP服务器，具有上下文感知AI交互能力。允许通过命令行参数动态配置根目录，或默认为当前工作目录。","maintainers":[{"name":"1587causalai","email":"zj3712@gmail.com"}],"readme":"# 可配置的个人文件系统 MCP 服务器 (Configurable Personal Filesystem MCP Server)\n\n**NPM 包名:** `@1587causalai/configurable-personal-fs-server`\n**版本:** `0.1.0`\n**作者:** `1587causalai`\n**仓库地址:** [https://github.com/1587causalai/servers/tree/main/src/filesystem](https://github.com/1587causalai/servers/tree/main/src/filesystem)\n\n这是一个定制版的模型上下文协议 (MCP) 文件系统操作服务器，旨在提供更强的灵活性和更好的人工智能 (AI) 交互体验。它允许用户通过命令行参数动态配置其服务的根目录，或者在未提供参数时默认使用当前工作目录。\n\n该服务器的一个关键特性是其**具备上下文感知能力的工具描述**，这显著改善了 AI 客户端 (如 Cursor) 理解和与服务器交互的方式。这使得命令执行更自然、更准确，尤其是在使用简洁的对话式指令时。\n\n此服务器基于原始的 `@modelcontextprotocol/server-filesystem` 构建，但针对个人文档管理和 AI 可用性进行了重要增强。\n\n## 主要特性\n\n*   继承自基础服务器的所有标准文件系统操作：\n    *   读/写文件\n    *   创建/列出/删除目录\n    *   移动文件/目录\n    *   搜索文件\n    *   获取文件元数据\n    *   支持差异比较的选择性文件编辑\n*   **动态根目录配置：**\n    *   通过命令行参数指定单个根目录。\n    *   如果未提供参数，则默认为当前工作目录 (`process.cwd()`)。\n*   **增强的 AI 上下文感知：**\n    *   工具描述采用中文，并动态包含配置好的 `dynamicBasePath` (动态基本路径)。\n    *   AI 客户端能更好地理解相对路径和服务器的操作上下文。\n    *   改进了自然语言交互 (例如，AI 能正确推断出类似 `@me 列出文件` 这类指令的目标目录)。\n*   **【个人文档专用】**：工具描述经过定制，以表明其专为个人文档管理而设计。\n\n## 安装与使用\n\n您可以使用 `npx` 直接运行此服务器：\n\n```bash\nnpx -y @1587causalai/configurable-personal-fs-server [您的文档路径]\n```\n\n*   如果提供了 `[您的文档路径]`，服务器将仅在该目录内操作。\n*   如果未提供路径，服务器将在执行命令时所在的当前工作目录内操作。\n\n## 客户端配置 (例如 Cursor 的 `mcp.json`)\n\n要将此服务器与 MCP 客户端 (如 Cursor) 一起使用，请将以下配置添加到客户端的 MCP 设置中：\n\n```json\n{\n  \"mcpServers\": {\n    \"my-docs\": { // 您可以选择任何别名，例如 \"me\", \"personal-docs\"\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@1587causalai/configurable-personal-fs-server\",\n        \"/您个人文档目录的绝对路径\" // 替换为您期望的目录\n      ],\n      \"timeout\": 60 // 可选\n    }\n  }\n}\n```\n\n如果您希望服务器默认使用其当前工作目录（对于 GUI 客户端，`npx` 的有效运行目录可能不太可预测），您可以省略路径参数：\n\n```json\n{\n  \"mcpServers\": {\n    \"my-cwd-docs\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@1587causalai/configurable-personal-fs-server\"\n      ]\n    }\n  }\n}\n```\n通常建议提供绝对路径以确保行为一致。\n\n## 开发历程与设计理念\n\n此服务器中的增强功能是逐步迭代开发的：\n\n1.  **初次定制：** 从硬编码目录开始，以理解基本概念。(详见: [`docs/my_first_customization.md`](../../docs/my_first_customization.md))\n2.  **灵活配置与 AI 上下文：** 实现了动态目录配置，并且至关重要地，改进了工具描述，使服务器在与 AI 交互时更\"智能\"。这通过允许更自然的语言命令，显著提高了可用性。(详见: [`docs/flexible_directory_config.md`](../../docs/flexible_directory_config.md))\n\n核心经验是\"描述工程\"在 MCP 框架中的重要性。精心设计的工具描述对于弥合人类意图与 AI 执行之间的差距至关重要。\n\n## API 工具\n\n此服务器提供以下工具。请注意，AI 所见的工具描述会动态引用配置的根路径 (`dynamicBasePath`)：\n\n*   **read_file**: 【个人文档专用】读取此个人文档 (`dynamicBasePath`) 内的指定文件...\n*   **read_multiple_files**: 【个人文档专用】同时读取此个人文档 (`dynamicBasePath`) 内的多个指定文件...\n*   **write_file**: 【个人文档专用】在此个人文档 (`dynamicBasePath`) 内创建新文件或覆写现有文件...\n*   **edit_file**: 【个人文档专用】对此个人文档 (`dynamicBasePath`) 内的指定文本文件进行基于行的编辑...\n*   **create_directory**: 【个人文档专用】在此个人文档 (`dynamicBasePath`) 内创建新目录...\n*   **list_directory**: 【个人文档专用】列出此个人文档 (`dynamicBasePath`) 内指定子路径下的文件和目录...\n*   **directory_tree**: 【个人文档专用】获取此个人文档 (`dynamicBasePath`) 内指定子路径下文件和目录的递归树状JSON视图...\n*   **move_file**: 【个人文档专用】在此个人文档 (`dynamicBasePath`) 内移动或重命名文件和目录...\n*   **search_files**: 【个人文档专用】在此个人文档 (`dynamicBasePath`) 内递归搜索文件和目录...\n*   **get_file_info**: 【个人文档专用】获取此个人文档 (`dynamicBasePath`) 内指定文件或目录的元数据...\n*   **list_allowed_directories**: 返回此【个人文档专用】服务器当前唯一配置允许操作的根目录: `dynamicBasePath`...\n\n(有关 AI 看到的完整动态描述，请参阅源代码 `index.ts`。)\n\n## 从源码构建\n\n如果您克隆了本仓库：\n1.  导航到 `src/filesystem` 目录。\n2.  安装依赖：`npm install`\n3.  构建 TypeScript 代码：`npm run build`\n\n编译后的输出文件将位于 `dist` 文件夹中。\n\n## 许可证\n\nMIT 许可证。详情请参阅主仓库中的 [LICENSE](../../LICENSE) 文件。\n","readmeFilename":"README.md"}