PIF Personal Intelligence Framework MCP Server

Overview

The PIF Personal Intelligence Framework MCP Server implements a Model Context Protocol (MCP) endpoint tailored for Personal Intelligence Framework (PIF) workflows. It provides a lightweight HTTP server that lets developer tools and AI models exchange structured context, dispatch tool actions (file management, retrieval, and reasoning helpers), and persist session continuity via a journaling/memory layer. The server is designed to sit between a user interface or orchestrator and one or more models, exposing a consistent set of tools and state so agents can perform repeatable, auditable tasks.

This server is useful when you need predictable, structured interactions between humans, tools, and models: ingest and version files, guide multi-step reasoning with explicit steps, and maintain a running journal of decisions and memories. By centralizing file operations and session continuity, the MCP server helps keep model prompts concise while preserving the context required for long-running or multi-turn workflows.

Features

• Exposes an MCP-compatible HTTP API for model/tool coordination
• File management: upload, list, download, and reference files in model contexts
• Structured reasoning support: attach step-by-step traces, checkpoints, and tool usage metadata
• Journaling/memory persistence: append and retrieve session notes for continuity across interactions
• Simple configuration via environment variables and a YAML/JSON config file
• Lightweight, easy to deploy locally or inside containers for development and integration

Installation / Configuration

Clone the repository, create a virtual environment, install requirements, and start the server. The commands below are example workflows; adjust paths and module names if your environment differs.

Clone and install

git clone https://github.com/hungryrobot1/MCP-PIF.git
cd MCP-PIF

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

Environment variables (examples)

export MCP_HOST=0.0.0.0
export MCP_PORT=3000
export MCP_API_KEY="your-api-key"      # optional API key for simple auth
export MCP_FILES_DIR="./data/files"
export MCP_JOURNAL="./data/journal.json"

Start the server (example using uvicorn)

uvicorn mcp_pif.app:app --host ${MCP_HOST} --port ${MCP_PORT} --reload

Example config file (config.yml)

host: 0.0.0.0
port: 3000
api_key: "your-api-key"
files_dir: "./data/files"
journal_path: "./data/journal.json"
max_upload_size_mb: 50

Available Tools / Resources

The MCP server exposes a toolset and a small set of REST endpoints for integration. Typical endpoints:

Tool types commonly provided:

• file: upload, read, link files into contexts
• memory/journal: append/query persistent notes and session state
• reasoning: store structured step traces and checkpoints for audits

Use Cases

1. File-backed code review session

• Upload a codebase snapshot via /files (POST).
• Send an MCP /mcp request containing the file references and an instruction like “Find potential security issues.” The model replies with structured reasoning steps referencing file ids.
• Persist findings to the journal with /journal (POST) for later review.

2. Guided multi-step problem solving

• Initiate a reasoning session by posting a /mcp request that asks the model to break a task into steps.
• As each step completes, append step results to the journal and update the MCP context with checkpoints so subsequent model calls have continuity and can avoid repeating work.

3. Personal knowledge continuity

• Daily interactions append concise notes or decisions to the journal, which the MCP server surfaces to models as memory when generating responses. This keeps long-lived projects cohesive across sessions and agents.

Quick HTTP Example

Upload a file (curl)

curl -X POST "http://localhost:3000/files" \
  -H "Authorization: Bearer ${MCP_API_KEY}" \
  -F "file=@./notes.txt"

Send an MCP request

curl -X POST "http://localhost:3000/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${MCP_API_KEY}" \
  -d '{
    "prompt": "Plan next steps for the project",
    "tools": ["journal", "files"],
    "context": { "recent_journal": "..." }
  }'

Notes for Developers

• Use the /tools endpoint to discover capabilities programmatically before composing MCP requests.
• Keep uploaded files small (or reference external storage) to avoid excessive server load.
• The journal is append-first: design read/query patterns in your client to avoid race conditions in concurrent sessions.

Repository and source code: https://github.com/hungryrobot1/MCP-PIF