{"id":26937548,"url":"https://github.com/hungryrobot1/MCP-PIF","last_synced_at":"2025-04-02T13:15:44.801Z","repository":{"id":274831911,"uuid":"923899029","full_name":"hungryrobot1/MCP-PIF","owner":"hungryrobot1","description":"A MCP implementation of the personal intelligence framework (PIF)","archived":false,"fork":false,"pushed_at":"2025-03-19T01:29:50.000Z","size":60,"stargazers_count":13,"open_issues_count":1,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-19T02:28:35.135Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hungryrobot1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-29T02:59:09.000Z","updated_at":"2025-03-19T01:29:53.000Z","dependencies_parsed_at":"2025-03-19T12:01:18.960Z","dependency_job_id":null,"html_url":"https://github.com/hungryrobot1/MCP-PIF","commit_stats":null,"previous_names":["hungryrobot1/mcp-pif"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hungryrobot1%2FMCP-PIF","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hungryrobot1%2FMCP-PIF/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hungryrobot1%2FMCP-PIF/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hungryrobot1%2FMCP-PIF/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hungryrobot1","download_url":"https://codeload.github.com/hungryrobot1/MCP-PIF/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246819779,"owners_count":20839095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-02T13:15:20.661Z","updated_at":"2025-04-02T13:15:44.796Z","avatar_url":"https://github.com/hungryrobot1.png","language":"TypeScript","funding_links":[],"categories":["AI Memory \u0026 RAG","Community Servers","📦 Other","Real-Time Collaboration","Table of Contents","Mcp Server Directories \u0026 Lists","🗂️ Extensions by Category"],"sub_categories":["Memory","Knowledge and Memory","🧠 Knowledge Base"],"readme":"# Model Context Protocol TypeScript Implementation\n\n## Overview\nThis 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.\n\n\u003ca href=\"https://glama.ai/mcp/servers/fr71fvl2at\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/fr71fvl2at/badge\" alt=\"MCP-PIF Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Quick Start\n\n### Prerequisites\n- Node.js 18+ and npm\n- TypeScript 5.0+\n- Model Context Protocol TypeScript SDK\n- Claude Desktop Client configured for custom servers\n\n\u003e **Note**: This implementation has been tested on both Windows and macOS/Linux systems.\n\n### Setup\n1. Clone the repository:\n```bash\ngit clone [https://github.com/hungryrobot1/MCP-PIF]\ncd mcp-pif\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Configure the server:\n   - Configuration is now auto-detected by default, but you can customize:\n     - Set the `MCP_WORKSPACE_ROOT` environment variable to specify a workspace location\n     - Or set the `MCP_CONFIG` environment variable with a JSON string of configuration options\n     - Or directly edit `src/config.ts` to modify the default configuration\n\n4. Build the server:\n```bash\nnpm run build\n```\n\n5. Configure Claude Desktop Client:\n   - Locate your Claude Desktop Client configuration directory\n   - Create or modify `claude_desktop_config.json`:\n     ```json\n     {\n         \"mcpServers\": {\n             \"mcp-pif\": {\n                 \"command\": \"node\",\n                 \"args\": [\"path/to/your/mcp-pif/build/index.js\"],\n                 \"cwd\": \"path/to/your/mcp-pif\",\n                 \"env\": {}\n             }\n         }\n     }\n     ```\n   - Replace `path/to/your/mcp-pif` with your actual repository path\n   - Paths are automatically normalized for your operating system\n\n6. Connect Claude Desktop Client:\n   - Start or restart the Claude Desktop Client\n   - Select \"mcp-pif\" as your custom server\n   - Start a new chat to begin using the server\n\n### Directory Structure\nThe server will create and manage the following structure in your configured workspace:\n```\nworkspace/\n├── home/\n│   ├── meta/\n│   │   └── journal/     # For storing journal entries\n│   └── projects/        # For user projects\n```\n\n### Next Steps\n- Review the [Module Documentation](home/meta/docs/modules/) for available tools\n- Explore the [Architecture Guide](home/meta/docs/architecture/) for implementation details\n- Check the [Development Guide](home/meta/docs/architecture/development.md) for contribution guidelines\n\n### Troubleshooting\n- If manually specifying paths, use platform-appropriate separators (backslashes on Windows, forward slashes on macOS/Linux)\n- Check the Claude Desktop Client logs if connection fails\n- Verify your workspace directory exists and is writable\n- Make sure Node.js and TypeScript versions meet requirements\n\n## Core Implementation\n\n### Available Tools\nThe implementation provides a set of core tools designed to support structured interaction:\n\n- **Filesystem Operations**: Navigate and manage workspace context\n  - `pwd`, `cd`, `read`, `write`, `mkdir`, `delete`, `move`, `rename`\n- **Reasoning Tools**: Create spaces for structured thought\n  - `reason`: Develop connected insights\n  - `think`: Create temporal spaces for contemplation\n- **Journal System**: Maintain framework continuity\n  - `journal_create`: Document developments\n  - `journal_read`: Explore patterns\n\n### Basic Usage\n```typescript\n// Create a structured thought pattern\nreason: {\n    thoughts: [\n        { content: \"Initial observation\" },\n        {\n            content: \"Building on previous thought\",\n            relationType: \"sequence\",\n            relationTo: 0\n        }\n    ]\n}\n\n// Document development\njournal_create: {\n    title: \"Implementation Pattern\",\n    content: \"Insights about development...\",\n    tags: [\"development\", \"patterns\"]\n}\n```\n\n## Cross-Platform Support\n\nThe MCP-PIF server is designed to work seamlessly on Windows, macOS, and Linux environments:\n\n### Path Handling\n- All file paths are automatically normalized for the current operating system\n- The workspace root is detected automatically based on the current environment\n- Both absolute and relative paths are supported within the workspace\n\n### Configuration\n- Environment variables provide a cross-platform way to configure the server\n- File operations use Node.js path methods to ensure consistent behavior\n- Journal entries and other data are stored in a platform-independent format\n\n### Development Workflow\n- NPM scripts work on all platforms\n- TypeScript compilation produces platform-agnostic JavaScript\n- Error handling accounts for platform-specific file system behaviors\n\n## Implementation Framework\n\n### Module Architecture\nThe system is built around modular tools that create conditions for structured emergence:\n```\nsrc/\n├── core/          # Framework foundations\n├── mcp_modules/   # Tool implementations\n└── api/           # External integrations\n```\n\n### Tool Patterns\nEach tool follows consistent patterns while maintaining its unique role:\n- Clear interface definitions\n- Structured error handling\n- State management\n- Cross-module interaction\n\n### Development Environment\n- TypeScript for type safety\n- Module-based organization\n- Comprehensive logging\n- Workspace context management\n\n## Theoretical Foundation\n\n### Personal Intelligence Framework\nThe PIF represents a new approach to human-AI collaboration based on:\n- Creating conditions for structured emergence\n- Maintaining framework-based continuity\n- Supporting progressive development\n- Enabling meaningful interaction\n\n### Structured Emergence\nRather than prescribing fixed patterns, the implementation creates bounded spaces where understanding can emerge through:\n- Tool-mediated interaction\n- Relationship structures\n- Temporal spaces\n- Progressive development\n\n### Framework-Based Continuity\nUnderstanding develops through:\n- Structured documentation\n- Pattern discovery\n- Historical context\n- Evolutionary development\n\n### Progressive Disclosure\nThe system supports different levels of engagement:\n- Immediate practical usage\n- Pattern discovery\n- Framework evolution\n- Philosophical alignment\n\n## Development Paths\n\n### Tool User\nFor those primarily interested in practical implementation:\n1. Start with basic tool usage\n2. Explore module documentation\n3. Develop interaction patterns\n4. Discover emerging capabilities\n\n### Framework Developer\nFor those interested in extending the system:\n1. Review module architecture\n2. Understand tool patterns\n3. Implement new capabilities\n4. Maintain framework alignment\n\n### Theoretical Explorer\nFor those interested in deeper patterns:\n1. Study implementation principles\n2. Observe emerging patterns\n3. Contribute to framework evolution\n4. Develop new understanding\n\n## Contributing\nThis project welcomes contributions that engage with both implementation and theoretical aspects:\n- Tool development\n- Documentation improvement\n- Pattern discovery\n- Framework evolution\n\n## Documentation\nComprehensive documentation is available:\n- [Module Documentation](home/meta/docs/modules/): Individual tool documentation\n- [Architecture Guide](home/meta/docs/architecture/): System design and patterns\n- [Development Guide](home/meta/docs/architecture/development.md): Implementation patterns\n\n## Future Directions\nThe project continues to evolve through:\n- New tool development\n- Pattern discovery\n- Framework refinement\n- Community engagement\n\n## Philosophy\nThis implementation embodies a view where:\n- Understanding emerges through structured interaction\n- Tools create spaces for new patterns\n- Development itself becomes philosophical inquiry\n- Human and AI intelligence co-evolve\n\n## Notes on Usage\nThe 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.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhungryrobot1%2FMCP-PIF","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhungryrobot1%2FMCP-PIF","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhungryrobot1%2FMCP-PIF/lists"}