docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거

Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
2026-07-05 00:33:48 +09:00
parent 1cfd3bbb56
commit 9148c358d0
6455 changed files with 1 additions and 86875 deletions
@@ -0,0 +1,289 @@
+---
+id: ai-mcp-server-building
+title: MCP Server 작성 — 도구 + 권한 + 배포
+category: Coding
+status: draft
+source_trust_level: B
+verification_status: conceptual
+created_at: 2026-05-09
+updated_at: 2026-05-09
+tags: [ai, mcp, tool, vibe-coding]
+tech_stack: { language: "TS / MCP SDK", applicable_to: ["Backend"] }
+applied_in: []
+aliases: [MCP server, tool design, sampling, OAuth MCP, Streamable HTTP]
+---
+
+# MCP Server Building
+
+> Tool wrap + 권한 + 배포 = MCP server. **Stdio (로컬) / Streamable HTTP (cloud, 2024+)**. 좋은 tool descrip + JSON Schema + 안전.
+
+## 📖 핵심 개념
+- Server: tools / resources / prompts 노출.
+- Client: Claude Desktop / Cursor / Cline.
+- Transport: stdio / SSE / Streamable HTTP.
+- Sampling: server 가 client 의 LLM 사용 가능.
+
+## 💻 코드 패턴
+
+### 기본 server (TS, stdio)
+```ts
+// server.ts
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+
+const server = new Server({ name: 'acme-tools', version: '1.0.0' }, {
+  capabilities: { tools: {}, resources: {}, prompts: {} },
+});
+
+// Tools 정의
+const tools = {
+  search_orders: {
+    schema: z.object({ email: z.string().email() }),
+    handler: async (input: { email: string }) => {
+      const orders = await db.orders.findByEmail(input.email);
+      return JSON.stringify(orders.slice(0, 10));
+    },
+    description: 'Search recent orders by customer email. Returns up to 10 orders.',
+  },
+  get_inventory: {
+    schema: z.object({ productId: z.string() }),
+    handler: async ({ productId }: { productId: string }) => {
+      const inv = await db.inventory.find(productId);
+      return JSON.stringify(inv);
+    },
+    description: 'Get current inventory for a product.',
+  },
+};
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: Object.entries(tools).map(([name, t]) => ({
+    name,
+    description: t.description,
+    inputSchema: zodToJsonSchema(t.schema),
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = tools[req.params.name as keyof typeof tools];
+  if (!tool) {
+    return { content: [{ type: 'text', text: `Unknown tool: ${req.params.name}` }], isError: true };
+  }
+  
+  const parsed = tool.schema.safeParse(req.params.arguments);
+  if (!parsed.success) {
+    return { content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }], isError: true };
+  }
+  
+  try {
+    const result = await tool.handler(parsed.data as any);
+    return { content: [{ type: 'text', text: result }] };
+  } catch (e) {
+    return { content: [{ type: 'text', text: `Error: ${(e as Error).message}` }], isError: true };
+  }
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### Tool description (LLM 이 잘 고르도록)
+```
+Bad:  "Get user data"
+Good: "Get a user's profile by ID. Returns name, email, plan, created_at. 
+       Use this when you need user details. Returns 404 if user not found."
+```
+
+→ LLM 이 언제 사용할지 명시.
+
+### Streamable HTTP transport (2024+)
+```ts
+// stream + persistent connection
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+const app = express();
+app.use(express.json());
+
+app.post('/mcp', async (req, res) => {
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  });
+  await server.connect(transport);
+  await transport.handleRequest(req, res, req.body);
+});
+
+app.listen(3000);
+```
+
+→ Cloud-deployed multi-user MCP.
+
+### OAuth (cloud server 보안)
+```ts
+// /authorize, /token endpoints
+// 사용자가 ChatGPT / Claude.ai 에서 OAuth flow
+// Server 가 user-scoped data 반환
+
+app.use('/mcp', requireOAuthToken, async (req, res) => {
+  const userId = await verifyToken(req.headers.authorization);
+  // userId scope 으로 server 호출
+});
+```
+
+### Resources (data exposure)
+```ts
+import { ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+  resources: [
+    { uri: 'acme://users/active', name: 'Active users', mimeType: 'application/json' },
+    { uri: 'acme://docs/api', name: 'API docs', mimeType: 'text/markdown' },
+  ],
+}));
+
+server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+  if (req.params.uri === 'acme://users/active') {
+    const users = await db.users.findActive();
+    return {
+      contents: [{
+        uri: req.params.uri,
+        mimeType: 'application/json',
+        text: JSON.stringify(users),
+      }],
+    };
+  }
+  throw new Error('Not found');
+});
+```
+
+### Prompts (재사용 template)
+```ts
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: [{
+    name: 'analyze-customer',
+    description: 'Analyze a customer\'s purchase history',
+    arguments: [{ name: 'email', required: true }],
+  }],
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  if (req.params.name === 'analyze-customer') {
+    return {
+      messages: [{
+        role: 'user',
+        content: {
+          type: 'text',
+          text: `Analyze ${req.params.arguments?.email}'s orders. Look for patterns, churn risk, upsell opportunities.`,
+        },
+      }],
+    };
+  }
+});
+```
+
+### Permissions / 안전
+```ts
+// Sensitive 작업 = 명시 confirm
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const dangerous = ['delete_user', 'send_email', 'charge_card'];
+  if (dangerous.includes(req.params.name)) {
+    // MCP 가 client 에 confirm 요청 (capability 가 elicitation)
+    const ok = await server.request({
+      method: 'elicitation/create',
+      params: {
+        message: `Confirm: ${req.params.name} on ${req.params.arguments}`,
+      },
+    });
+    if (!ok.confirmed) return { content: [...], isError: true };
+  }
+  // ...
+});
+```
+
+### Logging / observability
+```ts
+async function callTool(name: string, input: any) {
+  const t = Date.now();
+  try {
+    const result = await tools[name].handler(input);
+    log.info({ tool: name, ms: Date.now() - t, success: true });
+    return result;
+  } catch (e) {
+    log.error({ tool: name, ms: Date.now() - t, error: e });
+    throw e;
+  }
+}
+```
+
+### Test
+```ts
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const transport = new StdioClientTransport({ command: 'node', args: ['server.js'] });
+const client = new Client({ name: 'test', version: '1.0' }, { capabilities: {} });
+await client.connect(transport);
+
+const tools = await client.listTools();
+const result = await client.callTool({ name: 'search_orders', arguments: { email: 'a@b.com' } });
+expect(result.content).toBeDefined();
+```
+
+### Inspector (debug)
+```bash
+npx @modelcontextprotocol/inspector node server.js
+# UI 에서 tool 호출 / 결과 확인
+```
+
+### 배포
+```
+Local:        config 에 command path
+Cloud HTTP:   docker + behind LB + OAuth
+Distribution: npm package
+```
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "acme": {
+      "command": "node",
+      "args": ["/path/to/server.js"],
+      "env": { "DB_URL": "..." }
+    }
+  }
+}
+```
+
+## 🤔 의사결정 기준
+| 상황 | 추천 |
+|---|---|
+| 로컬 단일 user | stdio |
+| Multi-user cloud | Streamable HTTP + OAuth |
+| 회사 내부 도구 | Stdio + 사내 npm publish |
+| Public service | Streamable HTTP + OAuth + rate limit |
+| Sensitive | Confirmation + audit |
+| Quick prototype | stdio + inspector |
+
+## ❌ 안티패턴
+- **Tool description 빈약**: LLM 이 못 고름.
+- **Sensitive 자동 실행**: HITL.
+- **PII raw response**: 마스킹.
+- **Schema 자주 변경**: 등록된 client 깨짐.
+- **HTTP 무 OAuth prod**: 누구나 호출.
+- **Sync long task**: timeout. async + status tool.
+- **Tool 너무 많음 (50+)**: LLM 혼란. group / namespace.
+
+## 🤖 LLM 활용 힌트
+- Tool descrip = LLM prompt — 풍부 + 명확.
+- Zod schema → JSON Schema 자동.
+- Sensitive = elicitation.
+- HTTP cloud = OAuth.
+
+## 🔗 관련 문서
+- [[AI_MCP_Integration_Patterns]]
+- [[AI_Function_Calling_Deep]]
+- [[AI_Agentic_Patterns]]