模型上下文协议 TypeScript 实现

概述

该项目将模型上下文协议 (MCP) 作为个人智能框架 (PIF) 的具体体现。通过结构化的工具和渐进式交互模式，它为人类与人工智能之间理解的有意义的发展创造了空间。

快速入门

先决条件

• Node.js 18+ 和 npm

• TypeScript 5.0+

• 模型上下文协议 TypeScript SDK

• 为自定义服务器配置的 Claude 桌面客户端

注意：此实现已在 Windows 和 macOS/Linux 系统上测试过。

设置

1. 克隆存储库：

2. 安装依赖项：

3. 配置服务器：

   • 现在默认自动检测配置，但您可以自定义：

     • 设置MCP_WORKSPACE_ROOT环境变量以指定工作区位置

     • 或者使用配置选项的 JSON 字符串设置MCP_CONFIG环境变量

     • 或者直接编辑src/config.ts修改默认配置

4. 构建服务器：

5. 配置Claude桌面客户端：

   • 找到您的 Claude 桌面客户端配置目录

   • 创建或修改claude_desktop_config.json ：

     { "mcpServers": { "mcp-pif": { "command": "node", "args": ["path/to/your/mcp-pif/build/index.js"], "cwd": "path/to/your/mcp-pif", "env": {} } } }

   • 将path/to/your/mcp-pif替换为您的实际存储库路径

   • 路径会自动根据您的操作系统进行规范化

6. 连接 Claude 桌面客户端：

   • 启动或重新启动 Claude 桌面客户端

   • 选择“mcp-pif”作为您的自定义服务器

   • 开始新的聊天以开始使用服务器

目录结构

服务器将在您配置的工作区中创建并管理以下结构：

后续步骤

• 查看模块文档以了解可用的工具

• 探索架构指南以了解实施细节

• 查看开发指南以了解贡献指南

故障排除

• 如果手动指定路径，请使用适合平台的分隔符（Windows 上为反斜杠，macOS/Linux 上为正斜杠）

• 如果连接失败，请检查 Claude 桌面客户端日志

• 验证您的工作区目录存在且可写

• 确保 Node.js 和 TypeScript 版本满足要求

核心实现

可用工具

该实现提供了一组旨在支持结构化交互的核心工具：

• 文件系统操作：导航和管理工作区上下文

  • pwd 、 cd 、 read 、 write 、 mkdir 、 delete 、 move 、 rename

• 推理工具：为结构化思维创造空间

  • reason ：培养相关见解

  • think ：创造沉思的时间空间

• 期刊系统：保持框架的连续性

  • journal_create ：记录进展

  • journal_read ：探索模式

基本用法

跨平台支持

MCP-PIF 服务器设计用于在 Windows、macOS 和 Linux 环境中无缝运行：

路径处理

• 所有文件路径都会自动根据当前操作系统进行规范化

• 根据当前环境自动检测工作区根目录

• 工作区内支持绝对路径和相对路径

配置

• 环境变量提供了一种跨平台的服务器配置方式

• 文件操作使用 Node.js 路径方法来确保一致的行为

• 日记帐分录和其他数据以独立于平台的格式存储

开发工作流程

• NPM 脚本适用于所有平台

• TypeScript 编译生成与平台无关的 JavaScript

• 错误处理考虑了平台特定的文件系统行为

实施框架

模块架构

该系统围绕模块化工具构建，为结构化出现创造条件：

工具模式

每个工具都遵循一致的模式，同时保持其独特的作用：

• 清晰的接口定义

• 结构化错误处理

• 状态管理

• 跨模块交互

开发环境

• TypeScript 类型安全

• 基于模块的组织

• 综合日志记录

• 工作区上下文管理

理论基础

个人智能框架

PIF 代表了一种基于以下原则的人机协作新方法：

• 为结构化涌现创造条件

• 保持基于框架的连续性

• 支持渐进式发展

• 实现有意义的互动

结构化涌现

该实施并不规定固定的模式，而是创建有界的空间，通过以下方式可以产生理解：

• 工具介导的互动

• 关系结构

• 时间空间

• 渐进式发展

基于框架的连续性

理解通过以下方式发展：

• 结构化文档

• 模式发现

• 历史背景

• 进化发展

渐进式披露

该系统支持不同级别的参与：

• 立即实际使用

• 模式发现

• 框架演变

• 哲学一致性

发展路径

工具用户

对于那些主要对实际实施感兴趣的人：

1. 从基本工具的使用开始

2. 探索模块文档

3. 开发交互模式

4. 发现新兴能力

框架开发人员

对于那些有兴趣扩展系统的人：

1. 审查模块架构

2. 了解工具模式

3. 实现新功能

4. 保持框架一致性

理论探索者

对于那些对更深层次的模式感兴趣的人：

1. 研究实施原则

2. 观察新兴模式

3. 为框架发展做出贡献

4. 形成新的理解

贡献

该项目欢迎涉及实施和理论方面的贡献：

• 工具开发

• 文档改进

• 模式发现

• 框架演变

文档

提供全面的文档：

• 模块文档：单个工具文档

• 架构指南：系统设计和模式

• 开发指南：实现模式

未来方向

该项目将继续通过以下方式发展：

• 新工具开发

• 模式发现

• 框架细化

• 社区参与

哲学

此实现体现了以下观点：

• 通过结构化互动产生理解

• 工具为新模式创造空间

• 发展本身就成为哲学探究

• 人类与人工智能共同进化

使用须知

该系统不仅仅是一套工具，更是一个探索人类与人工智能如何通过结构化交互发展的空间。每一次会议都是探索新的理解与协作模式的机会。