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.03.运行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.mainChatGPT连接（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”？？？'删除等未完成标记
🏷️ 标签流
- PR创建 →运行自动验证
- 验证失败 →
needs-verification贴标签+详细反馈 - 验证成功 →
verified贴标签+needs-verification删除 - 手动评论 →最终批准后剩余时间（保留现有政策）
🔄 验证过程
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"])工作流示例:
- 保存文档草稿 →
obs.upsert_markdown()或者Obsidian自己写 - 质量检查 →
obs.lint_markdown()运行 - 结果摘要 →
gh.comment_pr()通过PR留下反馈 - 标签管理 →问题时
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
}
}🔄 生产流程
- 在Obsidian中创建文档
- 通过MCP在GitHub上创建分支/文件
- PR自动创建
- 人手动评论后不久
- 使用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螺栓路径
______________________________________________________________________
注意：剩下的总是手动进行，以保持代码质量。