tok_mcp
专门为AI Vive Coder设计体系结构的MCP
Claude、Cursor、GPT、Gemini等AI编码工具的用户在服务初始设计阶段 推荐最佳体系结构可以接收的模型上下文协议（MCP）服务器。
💡 核心原理
tok_mcp不直接设置环境。
取而代之的是， AI可识别的开发文档在存储库中创建。
┌─────────────────────────────────────────────────────────────────┐
│ tok_mcp가 하는 일 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ❌ 직접 서버 설정 │
│ ❌ 직접 Docker 실행 │
│ ❌ 직접 Terraform 적용 │
│ │
│ ✅ AI가 이해할 수 있는 구조화된 문서 생성 │
│ ✅ 사람이 읽을 수 있는 아키텍처 설명서 생성 │
│ ✅ 이후 AI가 이 문서를 읽고 개발 진행 │
│ │
└─────────────────────────────────────────────────────────────────┘生成的两个关键文件
| 文件 | 目标 | 目的 |
|---|---|---|
ARCHITECTURE.md | 👤 人员体系结构说明、决策理由、结构图 | |
.ai-context.yaml | 🤖 AI | 通过最少的代币了解整体结构，开发指南 |
your-project/
├── ARCHITECTURE.md ← 사람이 읽는 아키텍처 문서
├── .ai-context.yaml ← AI가 읽는 컨텍스트 파일
└── (이후 AI가 개발 시작)为什么这样做？
일반적인 접근:
MCP가 직접 설정 → 블랙박스 → 이해 없이 사용 → 문제 발생 시 대응 불가
tok_mcp 접근:
문서 생성 → AI/사람 모두 이해 → 근거 있는 개발 → 유지보수 가능______________________________________________________________________
📚 目录
______________________________________________________________________
🔰 初学者的说明
MCP是什么？
\*\*模型上下文协议（MCP）\*\* 增加新功能的插件是。
스마트폰 + 카메라앱 = 사진 촬영 가능
AI + tok_mcp = 아키텍처 설계 가능Vive Code是什么？
在与AI对话的同时编写代码的开发方式。
전통적인 개발:
문서 읽기 → 코드 작성 → 에러 검색 → 수정 → 반복...
바이브 코딩:
AI에게 "이거 만들어줘" → 완성!体系结构是什么？
配置服务 服务器、数据库和网络的设计图是。
🏠 집 = 설계도 필요
💻 서비스 = 아키텍처(설계도) 필요
예: 쇼핑몰 아키텍처
┌─────────────────────────────────────────┐
│ 사용자 → 웹서버 → API → 데이터베이스 │
│ ↓ │
│ 이미지 저장소 │
└─────────────────────────────────────────┘为什么需要tok_mcp？
虽然动态编码很快， 如果第一次设计不好的话 这是个大问题：
错误的设计结果 |------------|------| |数据库选择错误|重写完整代码| |服务器大小设置错误|资费炸弹or服务关闭| |忽略可扩展性|用户增加后从头开始开发|
由tok_mcp解决：
- 通过提问了解准确的要求
- 应用AWS/GCP验证的最佳实践
- 推荐符合预算的最佳配置
- 生成AI和人都能理解的文档
______________________________________________________________________
🚀 使用方法
设计分为三个阶段的体系结构
┌─────────────────────────────────────────────────────────────┐
│ STEP 1. 설치 (1분) │
│ ─────────────────── │
│ Claude Desktop 또는 Cursor에 tok_mcp 추가 │
├─────────────────────────────────────────────────────────────┤
│ STEP 2. 질문에 답하기 (3분) │
│ ─────────────────── │
│ AI: "어떤 서비스인가요?" │
│ 나: "회원가입 있는 할일 관리 앱이요" │
│ │
│ AI: "예상 사용자는?" │
│ 나: "하루 100명 정도?" │
│ │
│ AI: "월 예산은?" │
│ 나: "5만원 이내요" │
├─────────────────────────────────────────────────────────────┤
│ STEP 3. 문서 생성 │
│ ─────────────────── │
│ ✅ 아키텍처 문서 생성 완료! │
│ │
│ 📄 ARCHITECTURE.md ← 사람이 읽는 설계 문서 │
│ 🤖 .ai-context.yaml ← AI가 읽는 컨텍스트 │
│ │
│ → 이제 AI에게 "이 컨텍스트대로 API 만들어줘"라고 하면 끝! │
└─────────────────────────────────────────────────────────────┘实际对话示例
사용자: 아키텍처 설계해줘
tok_mcp: 몇 가지 질문드릴게요.
1. 어떤 플랫폼을 사용하시나요?
> AWS
2. 어떤 서비스인가요?
> B2B SaaS, 문서 협업 툴
3. 예상 규모는요?
> DAU 500명, 동시접속 50명
4. 월 예산은?
> $100 이내
5. 개발환경 문서도 포함할까요?
> 네
[문서 생성 중...]
✅ 아키텍처 문서 생성 완료!
생성된 파일:
📄 ARCHITECTURE.md - 아키텍처 상세 설명 (사람용)
🤖 .ai-context.yaml - AI 컨텍스트 파일 (AI용)
핵심 설계:
- 컴퓨팅: ECS Fargate (ARM64/Graviton)
- 데이터베이스: RDS PostgreSQL (t4g.micro)
- 캐시: ElastiCache Redis
- 저장소: S3 + CloudFront
- 예상 월 비용: ~$75
이제 AI에게 ".ai-context.yaml 참고해서 API 서버 만들어줘"라고 하시면,
AI가 아키텍처를 이해하고 그에 맞게 개발합니다.______________________________________________________________________
📦 安装方法
npm安装
npm install -g tok_mcpClaude桌面设置
claude_desktop_config.json 添加到文件：
{
"mcpServers": {
"tok_mcp": {
"command": "npx",
"args": ["-y", "tok_mcp"]
}
}
}设置文件位置：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
Cursor设置
.cursor/mcp.json 添加到文件：
{
"mcpServers": {
"tok_mcp": {
"command": "npx",
"args": ["-y", "tok_mcp"]
}
}
}验证安装
安装后询问AI：
"tok_mcp 도구 목록 보여줘"______________________________________________________________________
💡 活用方法
MCP工具列表
“工具”“说明”“使用示例” |------|------|----------| | design_architecture |交互式体系结构设计|“帮我设计体系结构” | get_aws_reference |查询AWS最佳实践|“告诉我SaaS的AWS架构” | recommend_cpu_arch |推荐CPU架构|“ARM vs x86在API服务器上？”| | generate_docs 创建体系结构文档“请创建文档” | estimate_cost |每月费用计算|“此配置的费用是多少？”| | get_scaling_strategy |提出扩张战略|“流量增加10倍？”
生成的文档
tok_mcp 两个关键文档创建：
1.ARCHITECTURE.md（人用）
开发人员可以阅读和理解的体系结构文档。
# 아키텍처 문서
## 개요
B2B SaaS 문서 협업 서비스를 위한 AWS 기반 아키텍처
## 아키텍처 다이어그램
┌─────────────────────────────────────────────────────┐
│ AWS Cloud │
├─────────────────────────────────────────────────────┤
│ Route53 → CloudFront → ALB │
│ ↓ │
│ ECS Fargate │
│ (ARM64/Graviton) │
│ ↓ │
│ ┌─────────────┴─────────────┐ │
│ ↓ ↓ │
│ RDS PostgreSQL ElastiCache │
│ (t4g.micro) (Redis) │
│ ↓ │
│ S3 │
│ (정적 파일) │
└─────────────────────────────────────────────────────┘
## 설계 결정 사항
### 왜 ECS Fargate인가?
- 소규모 팀에서 Kubernetes 운영 부담 제거
- 서버리스로 운영 비용 최소화
- 오토스케일링 자동 지원
### 왜 ARM(Graviton)인가?
- x86 대비 40% 비용 절감
- 컨테이너 워크로드에 최적화
- 대부분의 언어/프레임워크 지원
### 왜 PostgreSQL인가?
- 복잡한 쿼리 지원 (문서 검색)
- JSON 타입 네이티브 지원
- 확장성 좋음
## 예상 비용
| 서비스 | 사양 | 월 비용 |
|--------|------|---------|
| ECS Fargate | 0.5vCPU, 1GB | ~$15 |
| RDS PostgreSQL | t4g.micro | ~$15 |
| ElastiCache | t4g.micro | ~$12 |
| ALB | - | ~$20 |
| S3 + CloudFront | 50GB | ~$5 |
| **합계** | | **~$67** |
## 확장 전략
1단계 (DAU 1,000): 현재 구성 유지
2단계 (DAU 5,000): ECS 태스크 수 증가, RDS 스케일업
3단계 (DAU 10,000+): Aurora 전환 고려, 캐시 클러스터화2..ai-context.yaml（ai용)
AI是一个结构化文件，可以通过最少的令牌了解整个结构。
# .ai-context.yaml
# AI가 이 파일을 읽으면 프로젝트 아키텍처를 즉시 이해합니다
project:
name: "my-saas-app"
type: "b2b-saas"
description: "문서 협업 서비스"
architecture:
platform: aws
region: ap-northeast-2
style: containerized
compute:
service: ecs-fargate
cpu_arch: arm64
specs:
cpu: 0.5vCPU
memory: 1GB
scaling:
min: 1
max: 4
target_cpu: 70%
database:
primary:
type: postgresql
service: rds
instance: db.t4g.micro
storage: 20GB
cache:
type: redis
service: elasticache
instance: cache.t4g.micro
storage:
static:
service: s3
cdn: cloudfront
networking:
load_balancer: alb
dns: route53
ssl: acm
# AI 개발 가이드라인
dev_guide:
language: typescript
framework: fastapi # 또는 express, nestjs
orm: prisma # 또는 sqlalchemy
structure:
- "src/api/ - API 엔드포인트"
- "src/services/ - 비즈니스 로직"
- "src/repositories/ - 데이터 접근"
- "src/models/ - 타입 정의"
env_vars:
- DATABASE_URL
- REDIS_URL
- AWS_REGION
- AWS_S3_BUCKET
patterns:
- "REST API with OpenAPI spec"
- "Repository pattern for data access"
- "Structured JSON logging"
- "Health check endpoint at /health"
constraints:
- "ARM64 빌드 필수 (Graviton)"
- "Connection pooling 사용 (PgBouncer)"
- "S3 presigned URL로 파일 업로드"
estimated_cost: "$67/month"使用情形
方案1：启动新项目
나: "쇼핑몰 만들건데 아키텍처 설계해줘"
AI: (tok_mcp 질문 진행)
AI: "문서 생성 완료! ARCHITECTURE.md와 .ai-context.yaml 만들었어요"
나: ".ai-context.yaml 참고해서 백엔드 API 만들어줘"
AI: (컨텍스트 파일을 읽고 아키텍처에 맞게 개발 시작)方案2：加入新团队
새 팀원: "이 프로젝트 구조가 어떻게 되나요?"
AI: (ARCHITECTURE.md 읽음)
AI: "이 프로젝트는 AWS ECS Fargate 기반으로... (상세 설명)"场景3:AI上下文共享
나: "새 기능 추가해줘"
AI: (.ai-context.yaml 자동 참조)
AI: "현재 아키텍처(ECS Fargate + PostgreSQL)에 맞게 구현하겠습니다"文档结构
your-project/
│
├── ARCHITECTURE.md # 👤 사람이 읽는 아키텍처 문서
│ ├── 개요
│ ├── 아키텍처 다이어그램
│ ├── 설계 결정 사항 (ADR)
│ ├── 예상 비용
│ └── 확장 전략
│
├── .ai-context.yaml # 🤖 AI가 읽는 컨텍스트 파일
│ ├── 프로젝트 정보
│ ├── 아키텍처 스펙
│ ├── 개발 가이드라인
│ └── 제약사항
│
├── docs/ # 📚 추가 문서 (선택)
│ ├── SCALING.md # 확장 가이드
│ ├── COST.md # 비용 최적화
│ └── DEPLOYMENT.md # 배포 가이드
│
└── infrastructure/ # 🚀 인프라 코드 (선택)
├── terraform/
└── docker/______________________________________________________________________
📋 详细信息
推荐方式
1.基于AWS/GCP最佳实践
推荐基于经过验证的体系结构模式。
参考源：
- AWS架构良好的框架
- AWS解决方案库
- GCP参考架构
- Naver Cloud体系结构指南
2.推荐基于工作负载的CPU体系结构
| 工作负载 | 推荐理由 | |
|---|---|---|
| Web/API服务器 | ARM（重力） | 成本降低40% |
| ML推论 | ARM（重力） | 高性价比吞吐量 |
| 学习ML | x86+GPU 需要CUDA | |
| 高性能计算 | x86 | 单线程性能 |
| 传统应用程序 | x86 | 兼容性 |
| 集装箱 | ARM（重力） | 本机支持，降低成本 |
3.推荐不同规模的开发环境
规模容器协调CI/CD |------|---------|---------------|-------| |MVP | Docker编写|-| GitHub操作| |~1k DAU | Docker | ECS/云运行| GitHub操作| |约10k DAU | Docker | EKS/GKE | ArgoCD| |10k+DAU | Docker | Kubernetes | GitOps|
问题流
flowchart LR
subgraph Step1["STEP 1
기본 정보"]
S1A[플랫폼]
S1B[서비스 목적]
S1C[서비스 설명]
end
subgraph Step2["STEP 2
규모"]
S2A[예상 DAU]
S2B[동시 접속자]
S2C[일일 요청 수]
end
subgraph Step3["STEP 3
확장성"]
S3A[성장률]
S3B[트래픽 패턴]
S3C[글로벌 여부]
end
subgraph Step4["STEP 4
기술 요구사항"]
S4A[실시간 기능]
S4B[파일/미디어]
S4C[AI/ML]
end
subgraph Step5["STEP 5
예산"]
S5A[월 예산]
S5B[개발환경]
end
Step1 --> Step2 --> Step3 --> Step4 --> Step5
Step5 --> Result([📄 문서 생성])体系结构推荐决策
flowchart TD
Start([시작]) --> Q1{플랫폼?}
Q1 -->|AWS| AWS_Path
Q1 -->|GCP| GCP_Path
Q1 -->|Naver Cloud| NCP_Path
Q1 -->|개인서버| OnPrem[Docker Compose]
subgraph AWS_Path[AWS]
A1{서비스 유형?}
A1 -->|웹/API| A2{규모?}
A1 -->|게임| A3[GameLift]
A1 -->|AI/ML| A4[SageMaker]
A2 -->|소규모| A5[ECS Fargate]
A2 -->|중규모| A6[EKS]
A2 -->|대규모| A7[EKS + Multi-AZ]
end
subgraph GCP_Path[GCP]
G1{서비스 유형?}
G1 -->|웹/API| G2[Cloud Run / GKE]
G1 -->|게임| G3[GCE + Agones]
G1 -->|AI/ML| G4[Vertex AI]
end
subgraph NCP_Path[Naver Cloud]
N1{서비스 유형?}
N1 -->|웹/API| N2[Server + LB]
N1 -->|게임| N3[Gaming Server]
end
A3 & A4 & A5 & A6 & A7 --> CPU{CPU?}
G2 & G3 & G4 --> CPU
N2 & N3 --> CPU
OnPrem --> Doc
CPU -->|범용| ARM[ARM - Graviton]
CPU -->|고성능| X86[x86]
CPU -->|ML 학습| GPU[x86 + GPU]
ARM & X86 & GPU --> Doc([📄 문서 생성])______________________________________________________________________
🔧 详细结构
整体流程图
flowchart TB
subgraph User["👤 사용자"]
Q[질문: 아키텍처 설계해줘]
end
subgraph AI_Tool["🤖 AI 코딩 도구"]
Claude[Claude Desktop]
Cursor[Cursor]
GPT[ChatGPT]
Gemini[Gemini]
end
subgraph MCP["⚙️ tok_mcp 서버"]
direction TB
Handler[요청 핸들러]
subgraph Tools["MCP 도구들"]
T1[design_architecture]
T2[get_aws_reference]
T3[recommend_cpu_arch]
T4[generate_docs]
T5[estimate_cost]
end
subgraph Data["데이터 소스"]
AWS_Ref[(AWS 모범사례)]
GCP_Ref[(GCP 레퍼런스)]
Cost_DB[(비용 데이터)]
end
end
subgraph Output["📄 생성 문서"]
ARCH[ARCHITECTURE.md
사람용]
CTX[.ai-context.yaml
AI용]
end
subgraph Dev["🚀 개발 단계"]
AI_Dev[AI가 컨텍스트 읽고
개발 시작]
end
Q --> Claude & Cursor & GPT & Gemini
Claude & Cursor & GPT & Gemini |MCP 프로토콜| Handler
Handler --> Tools
Tools Data
Tools --> Output
Output --> AI_Dev处理过程（序列）
sequenceDiagram
participant U as 👤 사용자
participant AI as 🤖 AI (Claude/Cursor)
participant MCP as ⚙️ tok_mcp
participant DB as 📚 레퍼런스 DB
participant Repo as 📁 레포지토리
U->>AI: "아키텍처 설계해줘"
AI->>MCP: design_architecture 호출
loop 질문 단계
MCP->>AI: 질문 (플랫폼, 규모, 예산 등)
AI->>U: 질문 표시
U->>AI: 답변
AI->>MCP: 답변 전달
end
MCP->>DB: AWS/GCP 모범 사례 조회
DB-->>MCP: 매칭 아키텍처 패턴
MCP->>MCP: 아키텍처 설계
MCP->>MCP: 문서 생성
MCP-->>AI: 문서 내용 반환
AI->>Repo: ARCHITECTURE.md 저장
AI->>Repo: .ai-context.yaml 저장
AI-->>U: "문서 생성 완료!"
Note over U,Repo: 이후 개발 시
U->>AI: "API 만들어줘"
AI->>Repo: .ai-context.yaml 읽기
AI->>AI: 아키텍처 컨텍스트 이해
AI-->>U: 아키텍처에 맞는 코드 생성内部层次结构
graph TB
subgraph Layer1["🎯 인터페이스 계층"]
MCP_Server["MCP 서버 (JSON-RPC)"]
end
subgraph Layer2["🔧 도구 계층"]
Tool_Design["design_architecture"]
Tool_Ref["get_aws_reference"]
Tool_CPU["recommend_cpu_arch"]
Tool_Docs["generate_docs"]
Tool_Cost["estimate_cost"]
end
subgraph Layer3["⚡ 비즈니스 로직"]
Analyzer["요구사항 분석기"]
Matcher["패턴 매칭 엔진"]
DocGen["문서 생성기"]
Calculator["비용 계산기"]
end
subgraph Layer4["💾 데이터 계층"]
AWS_Patterns[("AWS 패턴 DB")]
GCP_Patterns[("GCP 패턴 DB")]
Pricing[("가격 DB")]
Templates[("문서 템플릿")]
end
Layer1 --> Layer2
Layer2 --> Layer3
Layer3 --> Layer4输出文档结构
graph LR
subgraph Output["tok_mcp 출력물"]
direction TB
subgraph Core["🎯 핵심 문서"]
ARCH["ARCHITECTURE.md
사람이 읽는 설계서"]
CTX[".ai-context.yaml
AI가 읽는 컨텍스트"]
end
subgraph Optional["📚 선택 문서"]
SCALE["SCALING.md"]
COST["COST.md"]
DEPLOY["DEPLOYMENT.md"]
end
subgraph Infra["🚀 인프라 코드 (선택)"]
TF["terraform/"]
Docker["docker/"]
end
end
ARCH --> |개발자가 읽고| Human[프로젝트 이해]
CTX --> |AI가 읽고| AI_Dev[개발 시작]
TF --> |선택적 사용| Deploy[인프라 배포]______________________________________________________________________
📍 路线图
- \[x\]基本体系结构推荐系统
- \[x\]创建ARCHITECTURE.md
- \[x\].ai-context.yaml创建
- \[\]AWS解决方案库集成
- \[\]生成Terraform代码（可选）
- \[\]创建Docker Compose（可选）
- \[\]成本模拟器
- \[\]扩大对GCP/Naver Cloud的支持
- \[\]生成体系结构图映像
______________________________________________________________________
赞助Talk Coding
______________________________________________________________________
📄 许可证
MIT许可证
______________________________________________________________________
🤝 贡献
欢迎话题和PR！
git clone https://github.com/seongminjaden/tok_mcp.git
cd tok_mcp
npm install
npm run dev