PIF

What is MCP-PIF?

MCP-PIF is a TypeScript implementation of the Personal Intelligence Framework (PIF) built on the Model Context Protocol (MCP). It aims to create a structured environment for human-AI collaboration by providing tools for file operations, structured reasoning, and journal-based documentation. The core idea is to foster a deeper understanding and continuity between human and AI interactions across sessions, allowing for the progressive development of insights.

How to use MCP-PIF?

To use MCP-PIF, you need Node.js 18+, npm, TypeScript 5.0+, and the Claude Desktop Client configured for custom servers. The setup involves:

1. Cloning the repository and navigating into the mcp-pif directory.
2. Installing dependencies using npm install.
3. Configuring the server: Configuration is auto-detected, but you can customize it via MCP_WORKSPACE_ROOT or MCP_CONFIG environment variables, or by editing src/config.ts.
4. Building the server with npm run build.
5. Configuring Claude Desktop Client: Modify claude_desktop_config.json to include mcp-pif as a custom server, specifying the command to run index.js.
6. Connecting Claude Desktop Client: Start or restart Claude Desktop Client and select "mcp-pif" as your custom server to begin a new chat.

The server will manage a workspace/ directory containing home/meta/journal/ for journal entries and home/projects/ for user projects.

Key Features of MCP-PIF

• Model Context Protocol (MCP) Implementation: Provides a framework for structured human-AI interaction.
• Personal Intelligence Framework (PIF): Supports continuity and evolving human-AI collaboration.
• Filesystem Operations: Tools like pwd, cd, read, write, mkdir, delete, move, rename for managing workspace context.
• Reasoning Tools: reason for developing connected insights and think for temporal contemplation.
• Journal System: journal_create to document developments and journal_read to explore patterns, maintaining framework continuity.
• Cross-Platform Support: Seamless operation on Windows, macOS, and Linux with automatic path normalization and environment variable-based configuration.
• Modular Architecture: Organized into core/, mcp_modules/, and api/ for clear structure and extensibility.
• Structured Emergence: Creates bounded spaces for understanding to emerge through tool-mediated interaction.
• Framework-Based Continuity: Develops understanding through structured documentation, pattern discovery, and historical context.
• Progressive Disclosure: Supports different levels of engagement from practical usage to philosophical alignment.

Use Cases of MCP-PIF

• Structured Human-AI Collaboration: Facilitates a more organized and meaningful interaction between humans and AI.
• Knowledge Management: The journal system and file operations allow for systematic documentation and retrieval of information.
• Project Development: Supports the management of user projects within a defined workspace.
• Research and Analysis: Reasoning tools can aid in developing connected insights and contemplative thought processes.
• Personal Intelligence Development: Helps in building and evolving a personal intelligence framework through continuous interaction and documentation.

FAQ about MCP-PIF

Q: What are the prerequisites for running MCP-PIF? A: You need Node.js 18+, npm, TypeScript 5.0+, and the Claude Desktop Client configured for custom servers.

Q: How do I configure the workspace root? A: You can set the MCP_WORKSPACE_ROOT environment variable, MCP_CONFIG environment variable with a JSON string, or directly edit src/config.ts.

Q: Is MCP-PIF cross-platform? A: Yes, it is designed to work seamlessly on Windows, macOS, and Linux, with automatic path normalization and environment variable-based configuration.

Q: What kind of tools does MCP-PIF provide? A: It provides filesystem operations (e.g., read, write), reasoning tools (reason, think), and a journal system (journal_create, journal_read).

Q: How does MCP-PIF support continuity in human-AI collaboration? A: Through its journal system and structured documentation, it helps maintain historical context and allows for the evolutionary development of understanding across sessions.

Model Context Protocol TypeScript Implementation

Overview

This project implements the Model Context Protocol (MCP) as a practical embodiment of the Personal Intelligence Framework (PIF). Through structured tools and progressive interaction patterns, it creates spaces for meaningful development of understanding between humans and AI.

Quick Start

Prerequisites

• Node.js 18+ and npm
• TypeScript 5.0+
• Model Context Protocol TypeScript SDK
• Claude Desktop Client configured for custom servers

Note: This implementation has been tested on both Windows and macOS/Linux systems.

Setup

1. Clone the repository:

git clone [https://github.com/hungryrobot1/MCP-PIF]
cd mcp-pif

2. Install dependencies:

npm install

3. Configure the server:

   • Configuration is now auto-detected by default, but you can customize:
     • Set the MCP_WORKSPACE_ROOT environment variable to specify a workspace location
     • Or set the MCP_CONFIG environment variable with a JSON string of configuration options
     • Or directly edit src/config.ts to modify the default configuration

4. Build the server:

npm run build

5. Configure Claude Desktop Client:

   • Locate your Claude Desktop Client configuration directory
   • Create or modify 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": {}
             }
         }
     }
     

   • Replace path/to/your/mcp-pif with your actual repository path
   • Paths are automatically normalized for your operating system

6. Connect Claude Desktop Client:

   • Start or restart the Claude Desktop Client
   • Select "mcp-pif" as your custom server
   • Start a new chat to begin using the server

Directory Structure

The server will create and manage the following structure in your configured workspace:

workspace/
├── home/
│   ├── meta/
│   │   └── journal/     # For storing journal entries
│   └── projects/        # For user projects

Next Steps

• Review the Module Documentation for available tools
• Explore the Architecture Guide for implementation details
• Check the Development Guide for contribution guidelines

Troubleshooting

• If manually specifying paths, use platform-appropriate separators (backslashes on Windows, forward slashes on macOS/Linux)
• Check the Claude Desktop Client logs if connection fails
• Verify your workspace directory exists and is writable
• Make sure Node.js and TypeScript versions meet requirements

Core Implementation

Available Tools

The implementation provides a set of core tools designed to support structured interaction:

• Filesystem Operations: Navigate and manage workspace context
  • pwd, cd, read, write, mkdir, delete, move, rename
• Reasoning Tools: Create spaces for structured thought
  • reason: Develop connected insights
  • think: Create temporal spaces for contemplation
• Journal System: Maintain framework continuity
  • journal_create: Document developments
  • journal_read: Explore patterns

Basic Usage

// Create a structured thought pattern
reason: {
    thoughts: [
        { content: "Initial observation" },
        {
            content: "Building on previous thought",
            relationType: "sequence",
            relationTo: 0
        }
    ]
}

// Document development
journal_create: {
    title: "Implementation Pattern",
    content: "Insights about development...",
    tags: ["development", "patterns"]
}

Cross-Platform Support

The MCP-PIF server is designed to work seamlessly on Windows, macOS, and Linux environments:

Path Handling

• All file paths are automatically normalized for the current operating system
• The workspace root is detected automatically based on the current environment
• Both absolute and relative paths are supported within the workspace

Configuration

• Environment variables provide a cross-platform way to configure the server
• File operations use Node.js path methods to ensure consistent behavior
• Journal entries and other data are stored in a platform-independent format

Development Workflow

• NPM scripts work on all platforms
• TypeScript compilation produces platform-agnostic JavaScript
• Error handling accounts for platform-specific file system behaviors

Implementation Framework

Module Architecture

The system is built around modular tools that create conditions for structured emergence:

src/
├── core/          # Framework foundations
├── mcp_modules/   # Tool implementations
└── api/           # External integrations

Tool Patterns

Each tool follows consistent patterns while maintaining its unique role:

• Clear interface definitions
• Structured error handling
• State management
• Cross-module interaction

Development Environment

• TypeScript for type safety
• Module-based organization
• Comprehensive logging
• Workspace context management

Theoretical Foundation

Personal Intelligence Framework

The PIF represents a new approach to human-AI collaboration based on:

• Creating conditions for structured emergence
• Maintaining framework-based continuity
• Supporting progressive development
• Enabling meaningful interaction

Structured Emergence

Rather than prescribing fixed patterns, the implementation creates bounded spaces where understanding can emerge through:

• Tool-mediated interaction
• Relationship structures
• Temporal spaces
• Progressive development

Framework-Based Continuity

Understanding develops through:

• Structured documentation
• Pattern discovery
• Historical context
• Evolutionary development

Progressive Disclosure

The system supports different levels of engagement:

• Immediate practical usage
• Pattern discovery
• Framework evolution
• Philosophical alignment

Development Paths

Tool User

For those primarily interested in practical implementation:

1. Start with basic tool usage
2. Explore module documentation
3. Develop interaction patterns
4. Discover emerging capabilities

Framework Developer

For those interested in extending the system:

1. Review module architecture
2. Understand tool patterns
3. Implement new capabilities
4. Maintain framework alignment

Theoretical Explorer

For those interested in deeper patterns:

1. Study implementation principles
2. Observe emerging patterns
3. Contribute to framework evolution
4. Develop new understanding

Contributing

This project welcomes contributions that engage with both implementation and theoretical aspects:

• Tool development
• Documentation improvement
• Pattern discovery
• Framework evolution

Documentation

Comprehensive documentation is available:

• Module Documentation: Individual tool documentation
• Architecture Guide: System design and patterns
• Development Guide: Implementation patterns

Future Directions

The project continues to evolve through:

• New tool development
• Pattern discovery
• Framework refinement
• Community engagement

Philosophy

This implementation embodies a view where:

• Understanding emerges through structured interaction
• Tools create spaces for new patterns
• Development itself becomes philosophical inquiry
• Human and AI intelligence co-evolve

Notes on Usage

The system is more than a set of tools - it is a space for exploring how human and AI intelligence can develop through structured interaction. Each session is an opportunity to discover new patterns of understanding and collaboration.