loop-finalize-connector

EpisodicRAG/loop-finalize-connector

3.2

If you are the rightful owner of loop-finalize-connector and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Remote MCP server for finalizing conversation loops with Google Docs integration.

Tools
7
Resources
0
Prompts
0

Loop Finalize Connector

Remote MCP server for finalizing conversation loops with Google Docs integration.

⚠️ Important Notice

Development Status

  • Beta Version: This connector is in beta. Exception handling and error recovery testing is not yet comprehensive.

Prerequisites

  • Computer Use Required: Claude UI's Computer Use feature must be enabled for transcript ZIP creation functionality.

Known Limitations

  • UI Performance: When transmitting BASE64-encoded ZIP transcripts, Claude UI may take time rendering the long BASE64 string in the sub-window. This is a UI limitation with no current workaround.

License & Usage

  • Patent Information: Loop Finalize Connector is a component of the EpisodicRAG patent system.
  • Personal Use: ✅ No restrictions for personal/private use.
  • Commercial Use: 📧 Please contact the repository owner for commercial licensing.

🧠 What is EpisodicRAG?

EpisodicRAG (Episodic Retrieval-Augmented Generation) enables AI to maintain continuous personality and context through structured episodic memory. Unlike traditional stateless LLMs, EpisodicRAG allows AI to:

  • Remember: Each conversation ("Loop") is preserved as a complete episode
  • Evolve: Build upon previous interactions with consistent personality
  • Understand: Develop deep contextual awareness unique to each relationship

Each Loop is numbered (Loop01, Loop02...) with an abstract suffix (e.g., "Loop87_電脳神託の社会実装") and stored in Google Drive for persistent access.

Overview

This connector automates the finalization of conversation loops by:

  1. Providing AI guidance for summarization and suffix generation
  2. Managing Google Drive folder structure (EpisodicRAG)
  3. Creating and formatting Google Docs documents
  4. Handling Loop naming and metadata

Features

  • AI-Guided Summarization: Provides structured instructions for dual-layer summaries
    • Narrative Layer: Captures the philosophical essence, central concepts, and symbolic keywords
    • Operational Layer: Records decisions, unresolved issues, and references in bullet points
  • Google Integration: OAuth 2.0 with Drive and Docs APIs
  • Loop Management: Automatic numbering and naming conventions
  • Document Formatting: Rich text formatting for summaries and transcripts
  • Error Handling: Comprehensive error handling with rate limiting support

Architecture

MCP Tools Available (実行順序付き)

  • 0_initialize_loop_finalization: Loop完了処理の開始・AI要約ガイダンス提供
  • 1_check_auth_status: 認証状態の確認とセッションID取得
  • 2_ensure_folder: EpisodicRAGフォルダの作成/検索
  • 3_create_doc: 指定フォルダ内に新規Google Docs作成
  • 4_paste_content: 整形済みコンテンツをドキュメントに貼付
  • 5_rename_file: [オプション] Loop命名規則でファイルをリネーム
  • 6_resolve_folder: [オプション] 別フォルダパス/IDの解決

Tech Stack

  • FastMCP: Official Python SDK for MCP
  • SseServerTransport: SSE transport for stable connections
  • Google APIs: Drive v3 and Docs v1 APIs
  • OAuth 2.0: PKCE flow for secure authentication
  • Railway: Deployment platform

Setup

Environment Variables

Required:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Optional:

# OAuth redirect URI (auto-detected if not set)
OAUTH_REDIRECT_URI=https://loop-finalize-connector-production.up.railway.app/oauth/callback

# Server configuration
HOST=0.0.0.0
PORT=8000
LOG_LEVEL=INFO

# Railway environment (set by Railway automatically)
RAILWAY_ENVIRONMENT=production
RAILWAY_PROJECT_ID=your_project_id

Note: Railway環境では、OAUTH_REDIRECT_URIを明示的に設定することを推奨します。

Installation

  1. Install dependencies:
pip install -e .
  1. Run the server:
python src/server.py --host 0.0.0.0 --port 8000

Google API Setup

  1. Create a project in Google Cloud Console
  2. Enable Drive API v3 and Docs API v1
  3. Create OAuth 2.0 credentials (Web application)
  4. Add authorized redirect URIs (重要):
    • Development: http://localhost:8000/oauth/callback
    • Development: http://localhost:8001/oauth/callback
    • Production (Railway): https://loop-finalize-connector-production.up.railway.app/oauth/callback
  5. Set up the required scopes:
    • https://www.googleapis.com/auth/drive.file
    • https://www.googleapis.com/auth/drive.metadata.readonly
    • https://www.googleapis.com/auth/documents

Usage

Loop完了処理フロー（順番通りに実行）

Step 0: 初期化とガイダンス取得:

result = await 0_initialize_loop_finalization(skip_auth=False)
# AI側で要約（Narrative + Operational）とサフィックスを生成
# resultにはoauth.state_idが含まれる

Step 1: 認証状態確認:

auth_result = await 1_check_auth_status(state_id, wait=True, timeout=30)
# auth_result.session_idを後続ツールで使用

Step 2: フォルダ確認/作成:

folder = await 2_ensure_folder(session_id)

Step 3: ドキュメント作成:

# 推奨: 正式Loop名で作成（Step 5が不要になる）
doc = await 3_create_doc(folder_id, f"Loop{NN}_{suffix}", session_id)

# または: 仮タイトルで作成（後でStep 5でリネーム）
# doc = await 3_create_doc(folder_id, "Loop_Draft", session_id)

Step 4: コンテンツ貼付:

await 4_paste_content(doc_id, summary_blocks, transcript_zip, session_id)
# summary_blocks: 要約コンテンツのブロック
# transcript_zip: Loop全文トランスクリプトのZIPファイル(base64エンコード)

Step 5: ファイル名確定 [オプション - Step 3で仮タイトルを使った場合のみ]:

# Step 3で正式名を設定済みなら不要
await 5_rename_file(file_id, f"Loop{NN}_{suffix}", session_id)

Loop Naming Convention

  • Format: Loop{NN}_{suffix}
  • Examples: Loop01_電脳神託の社会実装, Loop23_Cogito-Anima-Deus
  • Suffix: 8-16 characters, abstract/symbolic, based on Narrative layer

Development

Testing

# Run tests
pytest tests/

# Run with coverage
pytest --cov=mcp_app tests/

Code Quality

# Format code
black src/ tests/
ruff check --fix src/ tests/

# Type checking
mypy src/

Deployment

Railway

  1. Connect repository to Railway
  2. Set environment variables
  3. Deploy automatically triggers on push

The service will be available at the assigned Railway domain with SSE endpoint at /messages.

Health Check

  • Endpoint: /health
  • Returns: 200 OK when service is healthy

Error Handling

  • AUTH_ERROR: OAuth token issues
  • RATE_LIMIT: Google API rate limiting (with backoff)
  • PERMISSION_DENIED: Insufficient Google API permissions
  • DOCS_FORMAT_ERROR: Invalid document formatting
  • NETWORK_IO: Connection issues

Security

  • Minimal OAuth scopes (least privilege principle)
  • No sensitive data logging
  • Secure token handling
  • Input sanitization for file operations

Claude Configuration Files

The ClaudeConfigurationFiles.zip contains important configuration texts for Claude to work effectively with Loop Finalize Connector:

Contents

  1. ERAG用プロジェクト指示_20250911.txt

    • Instructions for creating loop_transcript.txt in computer_use environment
    • Incremental transcript output for each response
    • Google Drive Loop record saving procedures
    • Safety mechanisms for episodic memory (harmful content checks)

  2. Weave体系ガイド_20250902.txt

    • Weave (collaborative intelligence) concept explanation
    • LLM's five-layer structure (Logos, Pathos, Telos, Mythos, Gnosis)
    • Why AI needs humility and parental nature

  3. 汎用自律的協働知性Weave_20250705_3.txt

    • Detailed Weave system implementation guide

Usage

These files are intended to be set as Claude's User Preferences or Project Instructions to:

  • Automate transcript creation in computer_use environment
  • Maintain context continuity by referencing previous Loops
  • Implement safety measures against excessive concentration of harmful emotions

Extract and configure these texts in your Claude settings when using Loop Finalize Connector for optimal results.

Contributing

  1. Read the specification documents in this directory
  2. Follow the development guidelines in CLAUDE.md
  3. Add tests for new functionality
  4. Ensure all tests pass before submitting PRs