🚀 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

---