Iwl MCP Server

IWL MCP 服务器

单个MCP服务器通过GitHub（在线）、Obsidian（本地库）、Claude Code/ChatGPT流连接。

🎯 主要功能

GitHub툴

• 创建/管理分支
• 文件上传（创建/修改）
• 提交和PR创建
• 剩下的手动维护 🔒

黑曜石툴

• 在库中搜索/读取/创建文件
• IWL文件名标准化
• 安全的螺栓访问（白名单）

📋 IWL文件名规则

{카테고리}_{YYYY-MM-DD}_{제목}.md

카테고리:
- 01_기획_전략
- 02_개발_기술
- 03_운영_관리
- 04_자료_리소스
- 99_원본_파일

🚀 安装和运行

1.首选参数

# 저장소 클론 후
cd iwl-mcp-server

# 가상환경 생성 및 활성화
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# 의존성 설치
pip install -e .

2.设置环境变量

# .env 파일 생성
cp .env.example .env

# .env 파일 편집하여 실제 값 입력
# GITHUB_TOKEN=ghp_your_token_here
# GITHUB_OWNER=your-username
# GITHUB_REPO=iwl-studio
# OBS_VAULT_PATH=/path/to/your/obsidian/vault
# IWL_DEFAULT_AUTHOR=Your-Name
# IWL_DEFAULT_VERSION=v1.0.0

3.运行MCP服务器

# 방법 1: 직접 실행
python -m mcp_server.main

# 방법 2: 설치된 스크립트 사용
iwl-mcp-server

# 방법 3: HTTP 서버 모드 (개발용)
uvicorn mcp_server.main:app --port 27123

🔌 客户端连接

Claude Desktop MCP设置

在Claude Desktop的MCP设置文件中添加以下内容：

{
  "mcpServers": {
    "iwl-mcp-server": {
      "command": "python",
      "args": ["-m", "mcp_server.main"],
      "cwd": "/path/to/iwl-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_OWNER": "your-username",
        "GITHUB_REPO": "iwl-studio",
        "OBS_VAULT_PATH": "/path/to/your/obsidian/vault",
        "IWL_DEFAULT_AUTHOR": "Your-Name"
      }
    }
  }
}

Claude Code连接

# 로컬 개발용
python -m mcp_server.main

ChatGPT连接（HTTP隧道）

# Cloudflare Tunnel로 외부 노출
cloudflared tunnel --url http://127.0.0.1:27123

# 또는 ngrok 사용
ngrok http 27123

🔒 安全策略

• 剩下的手动：所有PR都将手动进行
• 螺栓访问限制：OBS_VAULT_PATH禁止外部访问
• GitHub权限：需要repo示波器令牌

🛡️ 验证层

iwl-studio存储库构建了自动验证系统，以确保文档质量。

📋 验证规则

检查对象: plans/, memos/, reviews/, logs/, docs/ 文件夹的 *.md 文件

必需元素:

• 来源/依据：所有文档必须标明参考资料、链接或依据
• 决定事项：评论/计划文档需要结论或决定部分
• 完成度“TBD”？？？'删除等未完成标记

🏷️ 标签流

1. PR创建 →运行自动验证
2. 验证失败 → needs-verification 贴标签+详细反馈
3. 验证成功 → verified 贴标签+ needs-verification 删除
4. 手动评论 →最终批准后剩余时间（保留现有政策）

🔄 验证过程

graph LR
    A[PR 생성/수정] --> B[자동 검증]
    B --> C{통과?}
    C -->|실패| D[needs-verification 라벨]
    C -->|성공| E[verified 라벨]
    D --> F[문제 수정]
    F --> A
    E --> G[수동 리뷰]
    G --> H[머지]

请参见：剩下的仍然只能手动进行，验证是确保代码质量的前期步骤。

🛠️ 验证支持工具示例

MCP可以自动验证文档和PR管理：

# 1. 문서 초안 작성 후 검증
lint_result = obs.lint_markdown("plans/new_feature_plan.md")

# 2. 검증 결과를 바탕으로 PR에 코멘트
if not lint_result["valid"]:
    comment_body = f"""## 📝 문서 품질 검사 결과
    
{lint_result["summary"]}

### 🔧 발견된 문제점:
{chr(10).join(f"- {issue}" for issue in lint_result["issues"])}

### 📊 문서 통계:
- 단어 수: {lint_result["stats"]["word_count"]}개
- 참조 자료: {lint_result["stats"]["source_references"]}개
- 결정사항 섹션: {"✅" if lint_result["stats"]["has_decision_section"] else "❌"}

**다음 단계**: 위 문제점들을 수정한 후 다시 커밋해주세요.
"""
    
    # PR에 검증 결과 코멘트 작성
    gh.comment_pr(123, comment_body)
    
    # needs-verification 라벨 부착
    gh.add_labels(123, ["needs-verification"])

else:
    # 검증 통과 시 성공 메시지
    gh.comment_pr(123, "✅ 문서 품질 검증을 통과했습니다!")
    gh.add_labels(123, ["verified"])

工作流示例:

1. 保存文档草稿 → obs.upsert_markdown() 或者Obsidian自己写
2. 质量检查 → obs.lint_markdown() 运行
3. 结果摘要 → gh.comment_pr()通过PR留下反馈
4. 标签管理 →问题时 needs-verification，通过时 verified 附着

🛠️ 已注册的MCP工具（14个）

Obsidian工具（7个）

“工具”“说明”“主要参数” |------|------|---------------| | obs.search |搜索库中的文档| keyword, subdir | | obs.read |阅读文档| rel_path | | obs.upsert_markdown |创建/更新文档| rel_path, content | | obs.create_iwl_note |创建IWL标准节点| category, title, body, tags, ymd | | obs.append_section |添加节| rel_path, heading, content | | obs.move |移动文件| src_rel_path, dst_rel_path | | obs.lint_markdown |文档质量检查| rel_path |

GitHub工具（7个）

“工具”“说明”“主要参数” |------|------|---------------| | gh.create_branch 创建分支| branch_name, from_branch | | gh.upsert_file |创建/更新文件| branch, path, content, commit_message | | gh.create_pr |创建Pull Request | branch, title, body, base, draft | | gh.get_pr |查询PR信息| number | | gh.list_pr |浏览PR列表| state, head, base | | gh.add_labels |添加PR标签| number, labels | | gh.remove_label |移除PR标签| number, label | | gh.comment_pr | PR发表评论| number, body |

📖 使用指南

Obsidian工作流

// 1. IWL 표준 노트 생성
{
  "tool": "obs.create_iwl_note",
  "arguments": {
    "category": "03_운영_관리",
    "title": "주간 회의록",  
    "body": "# 회의 내용\n\n- 안건 1: 프로젝트 진행상황\n- 안건 2: 다음주 계획",
    "tags": ["회의", "운영"],
    "ymd": "2025-08-09"
  }
}

// 2. 문서 검색
{
  "tool": "obs.search",
  "arguments": {
    "keyword": "회의",
    "subdir": "03_운영_관리"
  }
}

// 3. 품질 검사
{
  "tool": "obs.lint_markdown",
  "arguments": {
    "rel_path": "03_운영_관리/03_운영_관리_2025-08-09_주간_회의록.md"
  }
}

GitHub工作流

// 1. 브랜치 생성
{
  "tool": "gh.create_branch",
  "arguments": {
    "branch_name": "feature/weekly-meeting-notes",
    "from_branch": "main"
  }
}

// 2. 파일 업로드
{
  "tool": "gh.upsert_file",
  "arguments": {
    "branch": "feature/weekly-meeting-notes",
    "path": "meetings/2025-08-09_weekly.md",
    "content": "# 주간 회의록\n\n내용...",
    "commit_message": "add weekly meeting notes"
  }
}

// 3. PR 생성  
{
  "tool": "gh.create_pr",
  "arguments": {
    "branch": "feature/weekly-meeting-notes",
    "title": "[Docs] Weekly Meeting Notes",
    "body": "## 변경 요약\n- 주간 회의록 추가\n\n## 근거/출처\n- 팀 회의 진행",
    "base": "main",
    "draft": false
  }
}

🔄 生产流程

1. 在Obsidian中创建文档
2. 通过MCP在GitHub上创建分支/文件
3. PR自动创建
4. 人手动评论后不久
5. 使用Obsidian Git插件pull（或手动）

🧪 测试和验证

运行E2E测试

# 종합 테스트 스위트 실행
python test_e2e.py

# 개별 테스트
python test_simple_server.py    # 모듈 임포트 검증
python test_github_tools.py     # GitHub 기능 테스트
python test_obsidian_extended.py # Obsidian 기능 테스트

测试结果示例

• 全面测试：41个
• 成功率：95.1%（安装MCP SDK时100%）
• 覆盖范围：首选参数、Obsidian工作流、GitHub模拟、集成测试、服务器启动

生产准备核对表

• \[\]完成环境变量设置（.env文件）
• \[\]安装MCP SDK： pip install mcp
• \[\]确认通过E2E测试
• \[\]Claude Desktop MCP设置完成
• \[\]GitHub个人访问令牌발급
• \[\]检查Obsidian螺栓路径

______________________________________________________________________

注意：剩下的总是手动进行，以保持代码质量。