Model Context Protocol TypeScript Implementation

Overview

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

1. Install dependencies:

npm install

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

npm run build

1. 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
2. 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

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

• 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

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

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

Tool Patterns

• 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

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

Structured Emergence

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

Framework-Based Continuity

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

Progressive Disclosure

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

Development Paths

Tool User

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

Framework Developer

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

Theoretical Explorer

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

Contributing

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

Documentation

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

Future Directions

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

Philosophy

• 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