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

Clone the repository:

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

Install dependencies:

npm install

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
Build the server:

npm run build

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
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:

Start with basic tool usage
Explore module documentation
Develop interaction patterns
Discover emerging capabilities

Framework Developer

For those interested in extending the system:

Review module architecture
Understand tool patterns
Implement new capabilities
Maintain framework alignment

Theoretical Explorer

For those interested in deeper patterns:

Study implementation principles
Observe emerging patterns
Contribute to framework evolution
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.

MCP-PIF