The MCP-PIF server enables structured human-AI interaction through filesystem management, reasoning tools, and journaling.
Filesystem Operations: Navigate and manage files (
cd
,ls
,pwd
), create directories (mkdir
), and perform file operations like reading (read
), writing/modifying (write
), renaming (rename
), moving (move
), and deleting (delete
).Reasoning Tools: Develop connected insights (
reason
) and create temporal spaces for contemplation (think
).Journal System: Document developments (
journal_create
) and explore patterns in journal entries (journal_read
) based on date ranges or tags.Cross-Platform Support: Works seamlessly on Windows, macOS, and Linux with automatic path normalization.
Extensible Architecture: Supports progressive development through a modular design that allows for tool development and framework extension.
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:
Install dependencies:
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 locationOr set the
MCP_CONFIG
environment variable with a JSON string of configuration optionsOr directly edit
src/config.ts
to modify the default configuration
Build the server:
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 pathPaths 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:
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 insightsthink
: Create temporal spaces for contemplation
Journal System: Maintain framework continuity
journal_create
: Document developmentsjournal_read
: Explore patterns
Basic Usage
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:
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.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
This server implements the Model Context Protocol to facilitate meaningful interaction and understanding development between humans and AI through structured tools and progressive interaction patterns.
- Overview
- Quick Start
- Core Implementation
- Cross-Platform Support
- Implementation Framework
- Theoretical Foundation
- Development Paths
- Contributing
- Documentation
- Future Directions
- Philosophy
- Notes on Usage
Related Resources
Related MCP Servers
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -331
CodeAlive MCPofficial
-securityAlicense-qualityA Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.Last updated -54MIT License- -securityAlicense-qualityA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.Last updated -010MIT License
- -securityFlicense-qualityA basic Model Context Protocol server implementation that demonstrates core functionality including tools and resources for AI chat applications.Last updated -