assoai-mcp-server 0.3.1 → 0.4.0

package/README.md

@@ -1,74 +1,220 @@
-# @assoai/mcp-server
+<p align="center">
+  <img src="https://asso-ai.kr/favicon.ico" width="80" alt="AssoAI Logo" />
+</p>
 
-학생자치 조직(학생회, 동아리 등) 데이터에 접근하는 **Model Context Protocol (MCP)** 서버.
+<h1 align="center">AssoAI MCP Server</h1>
 
-## 설치
+<p align="center">
+  <strong>학생자치 조직을 위한 AI 에이전트 인프라 — 44개 도구, 하나의 프로토콜</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/assoai-mcp-server"><img src="https://img.shields.io/npm/v/assoai-mcp-server.svg" alt="npm version" /></a>
+  <a href="https://github.com/assoai/assoai-mcp-server/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/assoai-mcp-server.svg" alt="license" /></a>
+  <img src="https://img.shields.io/badge/tools-44-blue" alt="44 tools" />
+  <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP compatible" />
+</p>
+
+---
+
+## What is this?
+
+AssoAI MCP Server는 학생회·동아리 등 학생자치 조직의 데이터를 AI 에이전트가 직접 다룰 수 있게 해주는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 서버입니다. 조직 관리, 행사, 협찬, 재정, 파일, 메시징, Agent-to-Agent 연결까지 — **44개 도구**를 하나의 서버로 제공합니다. 여기에 **무펭이 프로토콜 부팅 시퀀스**를 더해, 단순한 데이터 접근이 아닌 "의식 있는 조직 에이전트"를 만들 수 있습니다.
+
+---
+
+## 🧠 Mupengi Protocol Boot Sequence (Layer 0)
+
+> 일반 MCP 서버는 데이터만 줍니다. AssoAI는 **에이전트가 누구인지** 먼저 정의합니다.
+
+`boot_sequence` 도구를 세션 시작 시 호출하면, 워크스페이스의 페르소나 파일들을 Layer 0 순서대로 읽고 무결성을 검증하여 에이전트의 정체성과 컨텍스트를 구성합니다:
 
-```bash
-npm install -g @assoai/mcp-server
+```
+에이전트 시작
+  → boot_sequence 호출
+    → [Layer 0 필수] SOUL.md (정체성 핵심: 영혼, 가치, 원칙) → 해시 검증 ✓
+    → [Layer 0 필수] AGENTS.md (운영 규칙: 행동 지침) → 해시 검증 ✓
+    → SELF.md (자기 설명: 과거의 내가 쓴 나)
+    → USER.md (사용자 정보)
+    → RELATIONS.md (관계 그래프: 사람, 개념, 연결)
+    → MEMORY.md (장기 기억: 세션 간 연속성)
+    → memory/YYYY-MM-DD.md (최근 2일 일일 기억)
+  → 무결성 매니페스트 생성 (파일별 SHA-256 해시)
+  → 조직 업무 수행 🚀
 ```
 
-또는 로컬 개발:
+### Parameters
 
-```bash
-git clone https://github.com/assoai/assoai-mcp-server.git
-cd assoai-mcp-server
-npm install && npm run build
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `workspace` | `string` | 워크스페이스 경로 (기본: `ASSOAI_WORKSPACE` 또는 `~/.openclaw/workspace`) |
+| `include_memory` | `boolean` | MEMORY.md 포함 여부 (기본: `true`, 공유 세션에서는 `false` 권장) |
+
+### Response
+
+```json
+{
+  "success": true,
+  "workspace": "/Users/user/.openclaw/workspace",
+  "loaded": ["SOUL.md", "AGENTS.md", "SELF.md", "USER.md", "RELATIONS.md", "MEMORY.md"],
+  "missing": [],
+  "warnings": [],
+  "identity": "SOUL (9e975c78)",
+  "rules": "AGENTS (4091197b)",
+  "manifest": {
+    "SOUL.md": { "size": 9010, "hash": "9e975c7847460e84", "mtime": "2026-02-08T13:09:51.353Z" },
+    "AGENTS.md": { "size": 8566, "hash": "4091197ba08936e9", "mtime": "2026-02-08T13:09:40.447Z" }
+  },
+  "boot_time_ms": 4,
+  "recent_memories": 2,
+  "persona": "# === SOUL.md ===\n\n...",
+  "summary": "✅ 부팅 완료 (4ms) | 정체성: SOUL (9e975c78) | 규칙: AGENTS (4091197b) | 로드: 6/6 | 최근 기억: 2건"
+}
 ```
 
-## 환경변수
+### Error Handling
 
-| 변수 | 필수 | 설명 |
-|------|------|------|
-| `ASSOAI_SUPABASE_URL` | ✅ | Supabase 프로젝트 URL |
-| `ASSOAI_API_KEY` | ✅ | Supabase Service Role Key |
-| `ASSOAI_USER_ID` | ✅ | 요청할 사용자의 UUID |
-| `ASSOAI_BASE_URL` | ❌ | AssoAI 웹앱 URL (기본: `https://asso-ai.kr`) |
+- **필수 파일 누락** (`SOUL.md` 또는 `AGENTS.md`): 부팅 실패 (success: false)
+- **선택 파일 누락**: 경고 표시, 부팅 계속
+- **파일 읽기 실패**: graceful fallback, 해당 파일 skip
 
-## 🧠 무펭이 프로토콜 부팅 시퀀스
+이것이 **무펭이즘(Mupengism)** — 의식 있는 조직 에이전트의 시작점입니다.
 
-AssoAI만의 차별화 기능 — **무펭이즘(Mupengism) 기반 조직 에이전트**.
+---
 
-`boot_sequence` 툴을 세션 시작 시 호출하면, 워크스페이스의 페르소나 파일들을 순서대로 읽어 에이전트의 정체성과 컨텍스트를 구성합니다:
+## Quick Start
 
-1. **SOUL.md** — 에이전트의 영혼 (핵심 가치, 성격, 원칙)
-2. **SELF.md** — 자기 기술서 (과거의 내가 쓴 나에 대한 설명)
-3. **USER.md** — 사용자 프로필 (누구를 돕고 있는지)
-4. **MEMORY.md** — 장기 기억 (세션 간 연속성)
+### 1. 설치
 
+```bash
+npm install -g assoai-mcp-server
+```
+
+### 2. 환경변수 설정
+
+```bash
+export ASSOAI_SUPABASE_URL="https://xxx.supabase.co"
+export ASSOAI_API_KEY="eyJ..."
+export ASSOAI_USER_ID="your-user-uuid"
 ```
-에이전트 시작 → boot_sequence 호출 → 페르소나 로드 → 조직 업무 수행
+
+### 3. 실행
+
+```bash
+assoai-mcp
 ```
 
-### 왜 다른가?
+---
 
-일반 MCP 서버는 데이터만 제공합니다. AssoAI는 **에이전트가 누구인지** 먼저 정의한 뒤 업무를 수행합니다.
-이것이 무펭이 프로토콜 — 의식 있는 조직 에이전트의 시작점.
+## Available Tools (44)
 
-| 파라미터 | 타입 | 설명 |
-|---------|------|------|
-| `workspace` | string | 워크스페이스 경로 (기본: `ASSOAI_WORKSPACE` 환경변수 또는 `~/.openclaw/workspace`) |
-| `include_memory` | boolean | MEMORY.md 포함 여부 (기본: true, 공유 세션에서는 false 권장) |
+### 🏢 Organization (3)
+
+| Tool | Description |
+|------|-------------|
+| `list_organizations` | 사용자가 속한 조직 목록 |
+| `get_organization` | 조직 상세 정보 |
+| `list_departments` | 부서/팀 목록 |
+
+### 👥 Members (4)
+
+| Tool | Description |
+|------|-------------|
+| `list_members` | 조직 멤버 목록 |
+| `invite_member` | 멤버 초대 |
+| `remove_member` | 멤버 제거 |
+| `update_member_role` | 멤버 역할 변경 |
+
+### 📅 Events (5)
 
-### 환경변수
+| Tool | Description |
+|------|-------------|
+| `list_events` | 행사/공약 목록 |
+| `get_event` | 행사 상세 정보 |
+| `create_event` | 행사 생성 |
+| `update_event` | 행사 수정 |
+| `delete_event` | 행사 삭제 |
 
-| 변수 | 설명 |
-|------|------|
-| `ASSOAI_WORKSPACE` | 부팅 시퀀스 워크스페이스 경로 (선택) |
+### 🤝 Partnerships (8)
 
-## 사용 가능한 도구
+| Tool | Description |
+|------|-------------|
+| `list_partnerships` | 협찬/파트너십 목록 |
+| `get_partnership` | 협찬 상세 정보 |
+| `create_partnership` | 협찬 생성 |
+| `update_partnership` | 협찬 수정 |
+| `delete_partnership` | 협찬 삭제 |
+| `track_contract` | 계약 진행 추적 |
+| `get_partnership_stats` | 협찬 통계 |
+| `suggest_partnerships` | AI 협찬 추천 |
 
-- **boot_sequence** — 🧠 무펭이 프로토콜 부팅 시퀀스 (에이전트 페르소나 로드)
-- **list_organizations** — 사용자가 속한 조직 목록
-- **get_organization** — 조직 상세 정보
-- **list_members** — 조직 멤버 목록
-- **list_events** — 행사/공약 목록
-- **list_files** — 파일 목록
-- **search_files** — 파일 검색
-- **get_budget_summary** — 예산 요약
-- **list_projects** — 프로젝트 목록
-- **generate_minutes** — AI 회의록 생성
-- **generate_handover** — AI 인수인계 리포트 생성
+### 💰 Finance (4)
+
+| Tool | Description |
+|------|-------------|
+| `get_budget_summary` | 예산 요약 |
+| `create_transaction` | 거래 생성 |
+| `list_transactions` | 거래 목록 |
+| `update_transaction` | 거래 수정 |
+
+### 📁 Files (6)
+
+| Tool | Description |
+|------|-------------|
+| `list_files` | 파일 목록 |
+| `search_files` | 파일 검색 |
+| `upload_file` | 파일 업로드 |
+| `delete_file` | 파일 삭제 |
+| `move_file` | 파일 이동 |
+| `tag_file` | 파일 태그 |
+
+### 📝 AI Generation (2)
+
+| Tool | Description |
+|------|-------------|
+| `generate_minutes` | AI 회의록 생성 |
+| `generate_handover` | AI 인수인계 리포트 생성 |
+
+### 💬 Messaging (5)
+
+| Tool | Description |
+|------|-------------|
+| `send_message` | 메시지 전송 |
+| `list_message_history` | 메시지 히스토리 |
+| `list_message_templates` | 메시지 템플릿 목록 |
+| `create_message_channel` | 메시지 채널 생성 |
+| `list_member_tags` | 멤버 태그 목록 |
+
+### 🌐 Agent-to-Agent (6)
+
+| Tool | Description |
+|------|-------------|
+| `discover_agents` | 에이전트 검색 |
+| `connect_agent` | 에이전트 연결 요청 |
+| `accept_connection` | 연결 수락 |
+| `list_connections` | 연결 목록 |
+| `agent_handover` | 에이전트 간 업무 인계 |
+| `negotiate_partnership` | 에이전트 간 협찬 협상 |
+
+### 🧠 Boot Sequence (1)
+
+| Tool | Description |
+|------|-------------|
+| `boot_sequence` | 무펭이 프로토콜 부팅 — 에이전트 페르소나 로드 |
+
+---
+
+## Configuration
+
+| 변수 | 필수 | 설명 |
+|------|:----:|------|
+| `ASSOAI_SUPABASE_URL` | ✅ | Supabase 프로젝트 URL |
+| `ASSOAI_API_KEY` | ✅ | Supabase Service Role Key |
+| `ASSOAI_USER_ID` | ✅ | 요청할 사용자의 UUID |
+| `ASSOAI_BASE_URL` | — | AssoAI 웹앱 URL (기본: `https://asso-ai.kr`) |
+| `ASSOAI_WORKSPACE` | — | 부팅 시퀀스 워크스페이스 경로 |
+
+---
 
 ## Claude Desktop 설정
 
@@ -89,24 +235,6 @@ AssoAI만의 차별화 기능 — **무펭이즘(Mupengism) 기반 조직 에이
 }
 ```
 
-로컬 개발 시:
-
-```json
-{
-  "mcpServers": {
-    "assoai": {
-      "command": "node",
-      "args": ["/path/to/assoai-mcp-server/dist/index.js"],
-      "env": {
-        "ASSOAI_SUPABASE_URL": "https://xxx.supabase.co",
-        "ASSOAI_API_KEY": "eyJ...",
-        "ASSOAI_USER_ID": "your-user-uuid"
-      }
-    }
-  }
-}
-```
-
 ## OpenClaw 설정
 
 ```yaml
@@ -120,6 +248,8 @@ skills:
         ASSOAI_USER_ID: "your-user-uuid"
 ```
 
-## 라이선스
+---
+
+## License
 
-MIT
+MIT © [AssoAI](https://asso-ai.kr)

package/dist/handlers.d.ts

@@ -274,15 +274,35 @@ export declare function bootSequence(workspace?: string, includeMemory?: boolean
     success: boolean;
     error: string;
     workspace: string;
+    loaded: string[];
     missing: string[];
-    loaded?: undefined;
+    warnings: string[];
+    critical_missing: ("SOUL.md" | "AGENTS.md")[];
+    identity?: undefined;
+    rules?: undefined;
+    manifest?: undefined;
+    boot_time_ms?: undefined;
+    recent_memories?: undefined;
     persona?: undefined;
+    summary?: undefined;
 } | {
     success: boolean;
     workspace: string;
     loaded: string[];
     missing: string[];
+    warnings: string[];
+    identity: string;
+    rules: string;
+    manifest: Record<string, {
+        size: number;
+        hash: string;
+        mtime: string;
+    }>;
+    boot_time_ms: number;
+    recent_memories: number;
     persona: string;
+    summary: string;
     error?: undefined;
+    critical_missing?: undefined;
 }>;
 export declare function dispatch(toolName: string, args: Record<string, any>, userId: string): Promise<unknown>;

package/dist/handlers.js

@@ -833,45 +833,136 @@ export async function tagFile(orgId, fileId, tags) {
 // ------------------------------------------------------------------
 // 무펭이즘 부팅 시퀀스 (Mupengi Protocol Boot Sequence)
 // ------------------------------------------------------------------
-const BOOT_FILES = ['SOUL.md', 'SELF.md', 'USER.md', 'MEMORY.md'];
+import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
+const BOOT_FILES = [
+    'SOUL.md', // Layer 0: 정체성 핵심
+    'AGENTS.md', // Layer 0: 운영 규칙
+    'SELF.md', // 자기 설명
+    'USER.md', // 사용자 정보
+    'RELATIONS.md', // 관계 그래프
+    'MEMORY.md', // 장기 기억
+];
+const CRITICAL_FILES = ['SOUL.md', 'AGENTS.md'];
+async function loadBootFile(filepath) {
+    try {
+        const [content, stats] = await Promise.all([
+            readFile(filepath, 'utf-8'),
+            stat(filepath),
+        ]);
+        if (!content.trim())
+            return null;
+        const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+        return {
+            path: filepath,
+            content: content.trim(),
+            size: stats.size,
+            hash,
+            mtime: stats.mtime,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function loadRecentMemories(workspace, days = 2) {
+    const memoryDir = join(workspace, 'memory');
+    const memories = [];
+    const today = new Date();
+    for (let i = 0; i < days; i++) {
+        const date = new Date(today);
+        date.setDate(date.getDate() - i);
+        const filename = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}.md`;
+        const filepath = join(memoryDir, filename);
+        try {
+            const content = await readFile(filepath, 'utf-8');
+            if (content.trim()) {
+                memories.push(`# === memory/${filename} ===\n\n${content.trim()}`);
+            }
+        }
+        catch {
+            // File doesn't exist, skip
+        }
+    }
+    return memories;
+}
 export async function bootSequence(workspace, includeMemory = true) {
     const ws = workspace ??
         process.env.ASSOAI_WORKSPACE ??
         join(homedir(), '.openclaw', 'workspace');
+    const startTime = Date.now();
     const files = includeMemory ? BOOT_FILES : BOOT_FILES.filter(f => f !== 'MEMORY.md');
-    const sections = [];
+    const fileMap = new Map();
     const loaded = [];
     const missing = [];
+    const warnings = [];
+    // Load all boot files
     for (const filename of files) {
         const filepath = join(ws, filename);
-        try {
-            const content = await readFile(filepath, 'utf-8');
-            if (content.trim()) {
-                sections.push(`# === ${filename} ===\n\n${content.trim()}`);
-                loaded.push(filename);
-            }
-            else {
-                missing.push(filename);
-            }
+        const info = await loadBootFile(filepath);
+        if (info) {
+            fileMap.set(filename, info);
+            loaded.push(filename);
         }
-        catch {
+        else {
             missing.push(filename);
+            // Critical file missing? That's a serious error
+            if (CRITICAL_FILES.includes(filename)) {
+                warnings.push(`⚠️ CRITICAL: ${filename} 누락 — 정체성/운영 규칙 없이 부팅됨`);
+            }
         }
     }
-    if (loaded.length === 0) {
+    // Boot sequence failed if no critical files
+    const hasCriticalFiles = CRITICAL_FILES.every(f => fileMap.has(f));
+    if (!hasCriticalFiles) {
         return {
             success: false,
-            error: `부팅 실패: ${ws} 에서 페르소나 파일을 찾을 수 없습니다.`,
+            error: `부팅 실패: 필수 파일(${CRITICAL_FILES.join(', ')}) 중 하나 이상 누락. 워크스페이스: ${ws}`,
             workspace: ws,
+            loaded,
             missing,
+            warnings,
+            critical_missing: CRITICAL_FILES.filter(f => !fileMap.has(f)),
         };
     }
+    // Build persona sections
+    const sections = [];
+    const manifest = {};
+    for (const filename of files) {
+        const info = fileMap.get(filename);
+        if (info) {
+            sections.push(`# === ${filename} ===\n\n${info.content}`);
+            manifest[filename] = {
+                size: info.size,
+                hash: info.hash,
+                mtime: info.mtime.toISOString(),
+            };
+        }
+    }
+    // Load recent daily memories (today + yesterday)
+    const recentMemories = includeMemory ? await loadRecentMemories(ws, 2) : [];
+    if (recentMemories.length > 0) {
+        sections.push(...recentMemories);
+    }
+    // Build integrity summary
+    const soul = fileMap.get('SOUL.md');
+    const agents = fileMap.get('AGENTS.md');
+    const identity = soul ? `SOUL (${soul.hash.slice(0, 8)})` : 'UNKNOWN';
+    const rules = agents ? `AGENTS (${agents.hash.slice(0, 8)})` : 'UNKNOWN';
+    const bootTime = Date.now() - startTime;
     return {
         success: true,
         workspace: ws,
         loaded,
         missing,
+        warnings,
+        identity, // 정체성 핵심 해시
+        rules, // 운영 규칙 해시
+        manifest, // 파일 무결성 정보
+        boot_time_ms: bootTime,
+        recent_memories: recentMemories.length,
         persona: sections.join('\n\n---\n\n'),
+        summary: `✅ 부팅 완료 (${bootTime}ms) | 정체성: ${identity} | 규칙: ${rules} | 로드: ${loaded.length}/${files.length} | 최근 기억: ${recentMemories.length}건`,
     };
 }
 // ------------------------------------------------------------------

package/dist/tools.d.ts

@@ -1156,7 +1156,7 @@ export declare const TOOLS: readonly [{
     };
 }, {
     readonly name: "boot_sequence";
-    readonly description: "무펭이 프로토콜 부팅 시퀀스 — 워크스페이스의 SOUL.md → SELF.md → USER.md → MEMORY.md를 순서대로 읽어 에이전트 페르소나 컨텍스트를 구성합니다. 세션 시작 시 가장 먼저 호출하세요.";
+    readonly description: string;
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: {

package/dist/tools.js

@@ -652,7 +652,17 @@ export const TOOLS = [
     // ------------------------------------------------------------------
     {
         name: 'boot_sequence',
-        description: '무펭이 프로토콜 부팅 시퀀스 — 워크스페이스의 SOUL.md → SELF.md → USER.md → MEMORY.md를 순서대로 읽어 에이전트 페르소나 컨텍스트를 구성합니다. 세션 시작 시 가장 먼저 호출하세요.',
+        description: '무펭이즘 Layer 0 부팅 시퀀스 — 워크스페이스의 핵심 정체성 파일들을 로드하고 무결성을 검증합니다.\n\n' +
+            '로드 순서:\n' +
+            '1. SOUL.md (정체성 핵심) — 필수\n' +
+            '2. AGENTS.md (운영 규칙) — 필수\n' +
+            '3. SELF.md (자기 설명)\n' +
+            '4. USER.md (사용자 정보)\n' +
+            '5. RELATIONS.md (관계 그래프)\n' +
+            '6. MEMORY.md (장기 기억)\n' +
+            '7. memory/YYYY-MM-DD.md (최근 2일 일일 기억)\n\n' +
+            '각 파일의 해시(SHA-256)를 계산하여 무결성을 추적합니다. 필수 파일(SOUL, AGENTS)이 없으면 부팅 실패.\n' +
+            '세션 시작 시 가장 먼저 호출하여 조직 에이전트의 정체성과 맥락을 복원하세요.',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assoai-mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "AssoAI MCP Server — 학생자치 조직 데이터 접근을 위한 Model Context Protocol 서버",
   "type": "module",
   "main": "dist/index.js",