# MCP Brain Server

AIエージェントに「統合的な知識」を提供するMCPサーバー

## コンセプト

**人間が仕事を覚えるように、AIも知識を学習する**

人間が仕事を習得するプロセス:

1. **観察**: 先輩のやり方を見る
2. **実践**: 自分でやってみる
3. **失敗**: うまくいかない
4. **修正**: フィードバックを受けて調整
5. **定着**: 繰り返して身につく

このサーバーは、AIエージェントに同様の学習サイクルを提供する。

## 機能

### 知識の参照

- タスクに関連する知識を検索
- 知識の詳細を取得

### 知識の学習

- 実行結果の記録（成功/失敗）
- 失敗からの改善点を知識に反映
- 新しい知識の自動生成

### 将来実装

- **自動削除（忘却）**: 使用頻度の低い知識を自動でアーカイブ・削除

## 知識の構造

```
mcp-brain-storage/          # Gitリポジトリ（Obsidianで開ける）
├── .index_cache.pkl        # キャッシュ
├── .index_hash
├── README.md
└── knowledge/              # 知識ファイルはここに配置
    ├── create-pr.md        # フラット形式（Obsidian互換）
    ├── deploy-staging.md
    └── git-commit.md
```

```yaml
---
name: create-pr
description: PRを作成したいとき
version: 1
created: 2025-12-01
---
```

```markdown
PRを作成する方法。

1. 変更をコミット
2. gh pr create --fill
3. レビュアーをアサイン
```

## Tools

| Tool     | 説明                                   |
| -------- | -------------------------------------- |
| `search` | タスクに関連する知識を検索             |
| `get`    | 知識の詳細を取得（関連知識も自動展開） |
| `create` | 新しい知識を作成                       |
| `update` | 既存の知識を更新                       |

### 関連知識の自動連想

`get` で知識を取得すると、**Embeddingベースの類似度**で関連する知識が自動的に展開されます。
手動でリンクを張る必要はありません。脳のように、意味的に近い知識が自動で連想されます。

`hops` パラメータで連想の深さを指定可能（デフォルト: 2）。

```python
# 2ホップ先まで関連知識を取得
get(name="create-pr", hops=2)
```

```json
{
  "name": "create-pr",
  "description": "PRを作成したいとき",
  "content": "## 手順...",
  "related": [
    {
      "name": "git-commit",
      "description": "変更をコミットしたいとき",
      "related": [
        {"name": "git-push", "description": "リモートにプッシュしたいとき", "related": []}
      ]
    }
  ]
}
```

## Git連携

### 自動バージョン管理

知識の作成・更新・削除は**自動的にGitにコミット**されます。

```bash
# 知識ディレクトリをGitリポジトリとして初期化
cd ~/.mcp-brain
git init
git remote add origin git@github.com:your-name/mcp-brain-knowledge.git

# 以降、知識の変更は自動でコミット・プッシュされる
```

### コミットメッセージ

操作に応じて自動生成されます:

- `create: {knowledge-name}` - 新しい知識を作成
- `update: {knowledge-name}` - 既存の知識を更新
- `forget: {knowledge-name}` - 知識を削除

### メリット

- 📝 **履歴管理**: 知識の変更履歴を追跡
- 🔄 **同期**: 複数デバイス間で知識を同期
- 👥 **共有**: チームで知識を共有
- 🔙 **復元**: 削除した知識を復元可能

## インストール

```bash
uv tool install . --force
```

## 開発コマンド

```bash
make help
make doctor
make deps
make lint
make fmt
make test
make dev ARGS="--help"
```

## 設定

### 共通知識（全プロジェクトで共有）

```json
{
  "mcpServers": {
    "brain": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tomoharu-hayashi/mcp-server-brain.git", "mcp-brain"],
      "env": {
        "MCP_BRAIN_DIR": "~/pj/my/mcp-brain-storage"
      }
    }
  }
}
```

### プロジェクト独立の知識

プロジェクトごとに完全に独立した知識空間を持たせる場合。

#### 1. プロジェクト内に知識ディレクトリを作成

```bash
cd /path/to/your-project
mkdir .brain
cd .brain
git init
git remote add origin git@github.com:your-name/your-project-brain.git
```

#### 2. MCP設定（プロジェクトごと）

VS Code / Cursor の場合、`.vscode/mcp.json` を作成:

```json
{
  "mcpServers": {
    "brain": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/tomoharu-hayashi/mcp-server-brain.git", "mcp-brain"],
      "env": {
        "MCP_BRAIN_DIR": "${workspaceFolder}/.brain"
      }
    }
  }
}
```

#### 3. .gitignore に追加

親リポジトリで `.brain/` が検知されないように:

```gitignore
.brain/
```

### 構成パターン

| パターン         | MCP_BRAIN_DIR               | 用途                                |
| ---------------- | --------------------------- | ----------------------------------- |
| 共通             | `~/pj/my/mcp-brain-storage` | 汎用ワークフロー（Git、PR作成など） |
| プロジェクト独立 | `${workspaceFolder}/.brain` | プロジェクト固有の知識              |
| チーム共有       | リポジトリ内 `.brain/`      | チームで知識を共有                  |