assoai-mcp-server 0.3.0 → 0.3.2

package/README.md

@@ -1,42 +1,186 @@
-# @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개 도구**를 하나의 서버로 제공합니다. 여기에 **무펭이 프로토콜 부팅 시퀀스**를 더해, 단순한 데이터 접근이 아닌 "의식 있는 조직 에이전트"를 만들 수 있습니다.
+
+---
+
+## 🧠 Mupeng-i Protocol Boot Sequence
+
+> 일반 MCP 서버는 데이터만 줍니다. AssoAI는 **에이전트가 누구인지** 먼저 정의합니다.
+
+`boot_sequence` 도구를 세션 시작 시 호출하면, 워크스페이스의 페르소나 파일들을 순서대로 읽어 에이전트의 정체성과 컨텍스트를 구성합니다:
+
+```
+에이전트 시작
+  → boot_sequence 호출
+    → SOUL.md (영혼: 핵심 가치, 성격, 원칙)
+    → SELF.md (자기 기술서: 과거의 내가 쓴 나)
+    → USER.md (사용자: 누구를 돕는가)
+    → MEMORY.md (장기 기억: 세션 간 연속성)
+  → 조직 업무 수행 🚀
+```
+
+| 파라미터 | 타입 | 설명 |
+|---------|------|------|
+| `workspace` | `string` | 워크스페이스 경로 (기본: `ASSOAI_WORKSPACE` 또는 `~/.openclaw/workspace`) |
+| `include_memory` | `boolean` | MEMORY.md 포함 여부 (기본: `true`, 공유 세션에서는 `false` 권장) |
+
+이것이 **무펭이즘(Mupengism)** — 의식 있는 조직 에이전트의 시작점입니다.
+
+---
+
+## Quick Start
+
+### 1. 설치
+
+```bash
+npm install -g assoai-mcp-server
+```
+
+### 2. 환경변수 설정
 
 ```bash
-npm install -g @assoai/mcp-server
+export ASSOAI_SUPABASE_URL="https://xxx.supabase.co"
+export ASSOAI_API_KEY="eyJ..."
+export ASSOAI_USER_ID="your-user-uuid"
 ```
 
-또는 로컬 개발:
+### 3. 실행
 
 ```bash
-git clone https://github.com/assoai/assoai-mcp-server.git
-cd assoai-mcp-server
-npm install && npm run build
+assoai-mcp
 ```
 
-## 환경변수
+---
+
+## Available Tools (44)
+
+### 🏢 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` | 행사 삭제 |
+
+### 🤝 Partnerships (8)
+
+| Tool | Description |
+|------|-------------|
+| `list_partnerships` | 협찬/파트너십 목록 |
+| `get_partnership` | 협찬 상세 정보 |
+| `create_partnership` | 협찬 생성 |
+| `update_partnership` | 협찬 수정 |
+| `delete_partnership` | 협찬 삭제 |
+| `track_contract` | 계약 진행 추적 |
+| `get_partnership_stats` | 협찬 통계 |
+| `suggest_partnerships` | 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_BASE_URL` | — | AssoAI 웹앱 URL (기본: `https://asso-ai.kr`) |
+| `ASSOAI_WORKSPACE` | — | 부팅 시퀀스 워크스페이스 경로 |
 
-- **list_organizations** — 사용자가 속한 조직 목록
-- **get_organization** — 조직 상세 정보
-- **list_members** — 조직 멤버 목록
-- **list_events** — 행사/공약 목록
-- **list_files** — 파일 목록
-- **search_files** — 파일 검색
-- **get_budget_summary** — 예산 요약
-- **list_projects** — 프로젝트 목록
-- **generate_minutes** — AI 회의록 생성
-- **generate_handover** — AI 인수인계 리포트 생성
+---
 
 ## Claude Desktop 설정
 
@@ -57,24 +201,6 @@ npm install && npm run build
 }
 ```
 
-로컬 개발 시:
-
-```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
@@ -88,6 +214,8 @@ skills:
         ASSOAI_USER_ID: "your-user-uuid"
 ```
 
-## 라이선스
+---
+
+## License
 
-MIT
+MIT © [AssoAI](https://asso-ai.kr)

package/dist/handlers.d.ts

@@ -270,4 +270,19 @@ export declare function tagFile(orgId: string, fileId: string, tags: string[]):
     original_name: any;
     tags: any;
 }>;
+export declare function bootSequence(workspace?: string, includeMemory?: boolean): Promise<{
+    success: boolean;
+    error: string;
+    workspace: string;
+    missing: string[];
+    loaded?: undefined;
+    persona?: undefined;
+} | {
+    success: boolean;
+    workspace: string;
+    loaded: string[];
+    missing: string[];
+    persona: string;
+    error?: undefined;
+}>;
 export declare function dispatch(toolName: string, args: Record<string, any>, userId: string): Promise<unknown>;

package/dist/handlers.js

@@ -5,6 +5,9 @@
  * 환경변수: ASSOAI_SUPABASE_URL, ASSOAI_API_KEY (service role key)
  */
 import { createClient } from '@supabase/supabase-js';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 let _supabase = null;
 function getSupabase() {
     if (_supabase)
@@ -828,6 +831,50 @@ export async function tagFile(orgId, fileId, tags) {
     return data;
 }
 // ------------------------------------------------------------------
+// 무펭이즘 부팅 시퀀스 (Mupengi Protocol Boot Sequence)
+// ------------------------------------------------------------------
+const BOOT_FILES = ['SOUL.md', 'SELF.md', 'USER.md', 'MEMORY.md'];
+export async function bootSequence(workspace, includeMemory = true) {
+    const ws = workspace ??
+        process.env.ASSOAI_WORKSPACE ??
+        join(homedir(), '.openclaw', 'workspace');
+    const files = includeMemory ? BOOT_FILES : BOOT_FILES.filter(f => f !== 'MEMORY.md');
+    const sections = [];
+    const loaded = [];
+    const missing = [];
+    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);
+            }
+        }
+        catch {
+            missing.push(filename);
+        }
+    }
+    if (loaded.length === 0) {
+        return {
+            success: false,
+            error: `부팅 실패: ${ws} 에서 페르소나 파일을 찾을 수 없습니다.`,
+            workspace: ws,
+            missing,
+        };
+    }
+    return {
+        success: true,
+        workspace: ws,
+        loaded,
+        missing,
+        persona: sections.join('\n\n---\n\n'),
+    };
+}
+// ------------------------------------------------------------------
 // Dispatcher
 // ------------------------------------------------------------------
 export async function dispatch(toolName, args, userId) {
@@ -923,6 +970,9 @@ export async function dispatch(toolName, args, userId) {
             return moveFile(args.org_id, args.file_id, args.folder_id);
         case 'tag_file':
             return tagFile(args.org_id, args.file_id, args.tags);
+        // Boot Sequence
+        case 'boot_sequence':
+            return bootSequence(args.workspace, args.include_memory ?? true);
         default:
             throw new Error(`Unknown tool: ${toolName}`);
     }

package/dist/index.js

@@ -19,7 +19,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
 // --- tools/call -------------------------------------------------------
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
-    if (!USER_ID) {
+    // boot_sequence doesn't require USER_ID
+    if (!USER_ID && name !== 'boot_sequence') {
         return {
             content: [
                 { type: 'text', text: 'Error: ASSOAI_USER_ID is not set' },

package/dist/tools.d.ts

@@ -1154,4 +1154,21 @@ export declare const TOOLS: readonly [{
         };
         readonly required: readonly ["org_id"];
     };
+}, {
+    readonly name: "boot_sequence";
+    readonly description: "무펭이 프로토콜 부팅 시퀀스 — 워크스페이스의 SOUL.md → SELF.md → USER.md → MEMORY.md를 순서대로 읽어 에이전트 페르소나 컨텍스트를 구성합니다. 세션 시작 시 가장 먼저 호출하세요.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workspace: {
+                readonly type: "string";
+                readonly description: "워크스페이스 디렉토리 경로 (기본값: ASSOAI_WORKSPACE 환경변수 또는 ~/.openclaw/workspace)";
+            };
+            readonly include_memory: {
+                readonly type: "boolean";
+                readonly description: "MEMORY.md 포함 여부 (기본값: true). 공유 세션에서는 false 권장";
+            };
+        };
+        readonly required: string[];
+    };
 }];

package/dist/tools.js

@@ -647,4 +647,25 @@ export const TOOLS = [
             required: ['org_id'],
         },
     },
+    // ------------------------------------------------------------------
+    // 무펭이즘 부팅 시퀀스 (Mupengi Protocol)
+    // ------------------------------------------------------------------
+    {
+        name: 'boot_sequence',
+        description: '무펭이 프로토콜 부팅 시퀀스 — 워크스페이스의 SOUL.md → SELF.md → USER.md → MEMORY.md를 순서대로 읽어 에이전트 페르소나 컨텍스트를 구성합니다. 세션 시작 시 가장 먼저 호출하세요.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspace: {
+                    type: 'string',
+                    description: '워크스페이스 디렉토리 경로 (기본값: ASSOAI_WORKSPACE 환경변수 또는 ~/.openclaw/workspace)',
+                },
+                include_memory: {
+                    type: 'boolean',
+                    description: 'MEMORY.md 포함 여부 (기본값: true). 공유 세션에서는 false 권장',
+                },
+            },
+            required: [],
+        },
+    },
 ];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "assoai-mcp-server",
-  "version": "0.3.0",
-  "description": "AssoAI MCP Server \u2014 \ud559\uc0dd\uc790\uce58 \uc870\uc9c1 \ub370\uc774\ud130 \uc811\uadfc\uc744 \uc704\ud55c Model Context Protocol \uc11c\ubc84",
+  "version": "0.3.2",
+  "description": "AssoAI MCP Server — 학생자치 조직 데이터 접근을 위한 Model Context Protocol 서버",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -36,4 +36,4 @@
     "bin",
     "README.md"
   ]
-}
+}