✨ Lucidity MCP 🔍

✨ Lucidity MCP 🔍

Lucidity は、インテリジェントなプロンプトベースの分析を通じて、AI が生成するコードの品質向上を支援するために設計された Model Context Protocol（MCP）サーバーです。AI コーディングアシスタントに構造化されたガイダンスを提供することで、Lucidity はよくある品質上の問題を特定して対処し、よりクリーンで保守しやすく、堅牢なコードの実現を支援します。

コミットする前に、自分でノリ任せにコードを書いて悪夢のような地獄絵図にしてしまうのではなく、Lucidity に変更を分析してもらいましょう！😱 💥 🚫

💫 機能

• 🔮 包括的な問題検出 - 複雑さからセキュリティ脆弱性まで、10 の重要な品質領域を対象とします
• 🔄 コンテキストに応じた分析 - 変更を元のコードと比較し、意図しない変更を特定します
• 🌐 言語に依存しない設計 - AI アシスタントが理解できるあらゆるプログラミング言語で動作します
• 🎯 対象を絞った分析 - プロジェクトのニーズに応じて、特定の問題の種類を対象にできます
• 📝 構造化された出力 - 明確な推奨事項を含む、実行可能なフィードバックを AI が提供できるよう支援します
• 🤖 MCP 統合 - Claude やその他の MCP 対応 AI アシスタントとシームレスに連携します
• 🪶 軽量な実装 - 依存関係を最小限に抑えたシンプルなサーバー設計です
• 🧩 拡張可能なフレームワーク - 新しい問題の種類を追加したり、分析基準を調整したりできます
• 🔀 柔軟なトランスポート - ターミナルベースのやり取りには stdio、ネットワーク通信には SSE をサポートします
• 🔄 Git を考慮した分析 - git diff から直接変更を分析するため、コミット前のレビューに最適です

🚀 インストール

# Clone the repository
git clone https://github.com/hyperbliss/lucidity-mcp.git
cd lucidity-mcp

# Set up a virtual environment with UV
uv venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies with UV
uv sync

📋 前提条件

• Python 3.13 以降
• Git（コード変更の分析に使用）
• UV パッケージマネージャー（依存関係の管理に推奨）

🔮 クイックスタート

Lucidity サーバーを起動する

# Start with stdio transport (for terminal use)
lucidity-mcp

# Start with SSE transport (for network use)
lucidity-mcp --transport sse --host 127.0.0.1 --port 6969

# Run with debug logging
lucidity-mcp --debug

# Run with file logging
lucidity-mcp --log-file lucidity.log

AI アシスタントでの使用

1. Lucidity を SSE モードで起動します：

   lucidity-mcp --transport sse
   

2. MCP プロトコル URI を使用して AI アシスタントに接続します：

   sse://localhost:6969/sse
   

3. AI は analyze_changes ツールを呼び出して、コード品質に関するフィードバックを取得できるようになります！

🧠 分析領域

Lucidity は、以下の 10 の重要な品質領域にわたってコードを分析します。

1. 不要な複雑さ - 過度に複雑なアルゴリズム、過剰な抽象化、複雑で分かりにくいロジックを特定します
2. 不適切な抽象化 - 漏れのある、または不適切な抽象化や、関心事の分離が不明確な状態を検出します
3. 意図しないコード削除 - 重要な機能や検証処理の誤った削除を検出します
4. 幻覚によるコンポーネント - 存在しない関数、クラス、API への参照を見つけます
5. スタイルの不統一 - プロジェクトのコーディング標準や規約からの逸脱を検出します
6. セキュリティ脆弱性 - コード変更に潜む潜在的なセキュリティ上の問題を特定します
7. パフォーマンスの問題 - パフォーマンスに影響を与える可能性のある非効率なアルゴリズムや処理を検出します
8. コードの重複 - リファクタリングすべき、繰り返されたロジックや機能を見つけます
9. 不完全なエラー処理 - 欠落または不十分な例外処理を検出します
10. テストカバレッジの不足 - 重要な機能に対するテストの欠落を特定します

📊 AI アシスタントへの質問例

Lucidity に接続した AI アシスタントで、次のような質問を試してみてください。

• 「最新の git 変更のコード品質を分析してください」
• 「JavaScript の変更にセキュリティ上の脆弱性がないか確認してください」
• 「Python コードがベストプラクティスに従っているか確認してください」
• 「最近のコード変更にパフォーマンスの問題がないか特定してください」
• 「最近のリファクタリングに意図しない副作用はありませんか？」
• 「コードの抽象化を改善するのを手伝ってください」
• 「重要な検証を誤って削除していないか確認してください」
• 「最新のコミットに幻覚による API 呼び出しがないか見つけてください」
• 「エラー処理は完全で堅牢ですか？」
• 「新機能にテストカバレッジの不足はありませんか？」

🛠️ 利用可能な MCP ツール

ツール

• analyze_changes - MCP を通じて分析できるように git の変更を準備します
  • パラメーター：
    • workspace_root：ワークスペース／git リポジトリのルートディレクトリ
    • path：分析する特定のファイルパス（任意）

💻 開発

Lucidity は、依存関係の管理と開発ワークフローに UV を使用します。UV は、高速で信頼性の高い Python パッケージマネージャーおよびリゾルバーです。

# Update dependencies
uv sync

# Run tests
pytest

# Run linting
ruff check .

# Run type checking
mypy .

🔧 ログの動作

Lucidity は、トランスポートに応じてログの処理方法を変えます。

• SSE トランスポート：コンソールへの完全なログ出力が有効になります
• --log-file を指定した Stdio トランスポート：すべてのログがファイルに出力され、コンソールへの出力は無効になります
• --log-file を指定しない Stdio トランスポート：警告とエラーのみが stderr に出力され、情報ログは無効になります

これにより、stdout にログが出力されて Stdio の通信が妨げられるのを防ぎます。

🎛️ コマンドラインオプション

usage: lucidity-mcp [-h] [--debug] [--host HOST] [--port PORT] [--transport {stdio,sse}]
                [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--verbose]
                [--log-file LOG_FILE]

options:
  -h, --help            show this help message and exit
  --debug               Enable debug logging
  --host HOST           Host to bind the server to (use 0.0.0.0 for all interfaces)
  --port PORT           Port to listen on for network connections
  --transport {stdio,sse}
                        Transport type to use (stdio for terminal, sse for network)
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Set the logging level
  --verbose             Enable verbose logging for HTTP requests
  --log-file LOG_FILE   Path to log file (required for stdio transport if logs enabled)

🤝 貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. UV で開発環境をセットアップします
4. 変更を加えます
5. テストと lint を実行します
6. 変更をコミットします（git commit -m 'Add some amazing feature'）
7. ブランチにプッシュします（git push origin feature/amazing-feature）
8. Pull Request を作成します

📝 ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については LICENSE ファイルをご覧ください。

---