Skip to content

README.md

Latest commit

 

History

History
198 lines (144 loc) · 3.82 KB

README.md

File metadata and controls

198 lines (144 loc) · 3.82 KB

🚀 MCP Transcript → PBL Generator

Server implementing MCP (Model Context Protocol) to process .jsonl transcripts
(Claude, ChatGPT exports, etc.) and generate Problem-Based Learning (PBL) logs in Markdown under docs/.

⚡ Turn raw AI conversations into structured, reusable knowledge.

🧠 What does it do?

This server:

  1. 📥 Parses .jsonl transcripts
  2. 🔍 Analyzes turns, errors, and structure
  3. 🧩 Extracts meaningful learning insights (PBL-style)
  4. 📝 Generates clean Markdown logs inside docs/

⚡ Quick Start

npm install
npm run start

Server endpoint:

http://localhost:3000/mcp

🔌 MCP Flow (Mental Model)

  1. Initialize session
  2. (Optional) Confirm initialization
  3. Call tools

👉 Think of it like a stateful API session

🛠️ Available Tools

  • transcript_health → Quick diagnostics of transcript integrity
  • pbl_parse_jsonl → Parses and structures transcript data
  • pbl_export_markdown → Generates a PBL learning log in Markdown

🔧 Example: Full Flow

1) Initialize Session

curl -i -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

👉 Save the mcp-session-id from response headers.

2) Send Initialized Notification (Recommended)

curl -i -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized",
    "params": {}
  }'

🧪 Tool Usage Examples

🔍 Parse Transcript

curl -i -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "pbl_parse_jsonl",
      "arguments": {
        "inputPath": "/path/to/transcript.jsonl"
      }
    }
  }'

Returns:

  • Summary (lines, turns, errors)
  • Structured data (turns, preview, etc.)

📝 Export PBL Markdown

curl -i -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'mcp-session-id: YOUR_SESSION_ID' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "pbl_export_markdown",
      "arguments": {
        "inputPath": "/path/to/transcript.jsonl",
        "outputPath": "docs/pbl/my-learning-log.md",
        "title": "Learning Log - Sprint 1",
        "projectName": "My MCP Server"
      }
    }
  }'

📁 Output Behavior

  • If outputPath is NOT provided:
docs/pbl/<input-file-name>-pbl.md

  • Security restriction:

    • Only paths inside docs/ are allowed

  • docs/ is ignored by Git (.gitignore)

⚡ CLI Usage (NPX)

npx mcp-transcript

Runs MCP over stdio (perfect for local integrations / Codex workflows)

🔧 Environment Variables

  • PORT → default 3000
  • MCP_PATH → default /mcp
  • ALLOWED_ORIGINS → CSV
  • SESSION_TTL_MS
  • RATE_LIMIT
  • RATE_WINDOW_MS

💡 Why this exists

Working with AI generates a LOT of knowledge… but it’s messy.

This tool helps you:

  • Convert conversations → learning artifacts
  • Build personal knowledge bases
  • Track problem-solving evolution
  • Reuse insights instead of losing them