使用说明

MCP服务器Starterkit-Kiro&Claude Code开发指南

这个项目 能动型IDE利用 Model Context Protocol（MCP）服务器可以半自动开发的入门级模板。基罗我 克劳德代码 您可以使用相同的AI开发工具高效地构建MCP服务器。

🚀 快速入门

1.克隆和设置项目

git clone <repository-url>
cd nodejs-mcp-server-starter-kit

pnpm install

2.首选参数

# 로컬 개발 환경 설정
cp env/local.env .env

# 환경 변수 편집
vim .env

3.运行服务器

# STDIO 모드 (기본)
pnpm dev

# HTTP 모드 (서버 환경 테스트)
pnpm dev:http

🎯 核心概念

MCP（模型上下文协议）란?

MCP是AI模型和外部系统之间的标准通信协议。

工具：AI可以执行的动作（搜索、计算、API调用）
资源：AI可以引用的数据（文档、记录）
~~提示：可选的可重复使用提示模板~~

Tool Spec First开发

PRD.md 创建→项目摘要
tool_spec.json 合成→规格定义
代码实现 →根据规格开发
测试 →验证规格合规性

🛠️ 使用Kiro/Claude Code开发MCP服务器

步骤0：设置Context7

背景7 访问页面，为我使用的Agentic IDE（Kiro，Claude Code）设置context7mcp

步骤1：创建产品需求文档（PRD）

利用Claude Code等方便的LLM创建需求整理文档， PRD.md 添加到

如果你没有写过PRD， ALPS写入器MCP 使用推荐

步骤2：创建工具规范

首先，请向AI工具发出以下请求：

"#File docs/TOOL_SPEC_GUIDE.md 과 PRD.md 파일을 읽고, tool_spec.json을 작성해줘.
- 상품명으로 검색 (필수)
- 카테고리 필터링 (선택)
- 최대 3개 결과 반환
- 영어 키워드만 지원
- TOOL_SPEC_GUIDE.md의 베스트 프랙티스를 모두 적용해줘"

预计结果：

{
  "tools": [
    {
      "name": "search_products",
      "description": "상품을 검색합니다. 영어 키워드만 지원하며 최대 3개 결과를 반환합니다.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "검색할 상품명 키워드 (영어만 지원)",
            "minLength": 1,
            "maxLength": 100
          },
          "category": {
            "type": "string",
            "description": "상품 카테고리",
            "enum": ["HOBBIES", "BAGS", "GAMES"]
          }
        },
        "required": ["name"]
      }
    }
  ]
}

步骤3:实施Vertical Slice

请向AI工具发出以下请求：

"#File tool_spec.json과 #File docs/IMPLEMENTATION_GUIDE.md를 참조해서 search_products 기능을 구현해줘.
- Controller: MCP 인터페이스 (#File docs/MCP_SERVER.md의 Tool 구현 베스트 프랙티스 적용)
- Service: 비즈니스 로직
- Adapter: OpenSearch 연동
- 입력 검증은 tool_spec.json 제약 조건을 Zod 스키마로 정확히 구현
- IMPLEMENTATION_GUIDE.md의 단계별 구현 방법을 정확히 따라줘"

要创建的文件结构：

src/tools/search_products/
├── controller.ts    # MCP 인터페이스 + Zod 스키마
├── service.ts       # 비즈니스 로직
├── adapter.ts       # OpenSearch 연동
└── index.ts         # 모듈 내보내기

步骤4：设置依赖注入

请向AI工具发出以下请求：

"#File docs/IMPLEMENTATION_GUIDE.md의 Step 6, Step 8을 참조해서 DIContainer에 search_products 기능을 등록하고, server.ts에서 MCP 도구로 등록하는 코드를 추가해줘.
- 의존성 주입 컨테이너 패턴을 정확히 따라줘
- 싱글톤 인스턴스 관리 방식 적용
- MCP SDK 등록 방법 준수"

步骤5：创建测试（可选）

请向AI工具发出以下请求：

"#File tool_spec.json과 #File docs/TESTING_GUIDE.md를 참조해서 Tool Spec 준수를 검증하는 테스트를 작성해줘.
- Tool Spec First 테스트 원칙 적용 (TESTING_GUIDE.md 2.1절 참조)
- Zod 스키마 검증 테스트
- 필수 매개변수 검증
- enum 값 검증
- 에러 케이스 테스트
- Vitest 사용"

📁 项目结构

├── src/
│   ├── server.ts                    # 메인 서버
│   ├── interfaces/                  # 공통 인터페이스
│   │   ├── mcp.ts                  # MCP 응답 표준화
│   │   └── product.ts              # 도메인 모델
│   ├── tools/                      # MCP Tools (액션)
│   │   └── search_products/        # Vertical Slice
│   │       ├── controller.ts
│   │       ├── service.ts
│   │       ├── adapter.ts
│   │       └── index.ts
│   ├── resources/                  # MCP Resources (데이터)
│   │   └── products/               # Vertical Slice
│   ├── di/container.ts             # 의존성 주입
│   ├── config/server.ts            # 설정
│   └── utils/                      # 공통 유틸리티
├── docs/                           # 상세 문서
├── env/                            # 환경별 설정
├── tool_spec.json                  # Tool 스펙 정의
├── package.json                    # 프로젝트 설정
└── tsconfig.json                   # TypeScript 설정

🤖 AI工具使用技巧

使用Kiro时

# 可通过命令引用上下文（代码库、文件、在线文档等）

#Folder docs/TOOL_SPEC_GUIDE.md 를 참조해서 ...

使用Claude Code时

运行Claude Code

claude

利用CLAUDE.md

项目根的 CLAUDE.md在中设置了项目说明，Claude Code将自动识别上下文。

# 개발 요청 예시
"docs/TOOL_SPEC_GUIDE.md와 docs/IMPLEMENTATION_GUIDE.md를 참조해서 tool_spec.json을 작성해줘"

📚 详细指南

项目的 docs/ 文件夹包含以下详细指南：

必需文档

工具_规格_ GIDE.md -tool_spec.json编写指南（开发起点）
实施_ GIDE.md -分阶段实施方法
MCP_SERVER.md -Tool和Resource最佳实践

参考文档

建筑_ IAGRAMS.md -可视化系统结构
测试指南.md -测试策略和实施
CONFIG_ENVIRONMENT.md -首选参数和部署
DOCKER_GUIDE.md -运行Docker容器

🔧 开发工作流

添加新功能

请求AI工具

"#Folder docs/를 참조해서 새로운 기능 'user_profile' Tool을 추가하고 싶어.
- #File docs/TOOL_SPEC_GUIDE.md를 기반으로 tool_spec.json부터 작성
- #File docs/IMPLEMENTATION_GUIDE.md의 새로운 기능 추가 방법 (4단계) 적용
- #File docs/MCP_SERVER.md의 Tool 구현 베스트 프랙티스 준수
- 전체 Vertical Slice를 Tool Spec First 원칙으로 구현해줘"

生成的结构

src/tools/user_profile/
├── controller.ts
├── service.ts
├── adapter.ts
└── index.ts

自动注册
- 添加对DIContainer的依赖性
- 在server.ts中注册Tool
- 在不修改现有代码的情况下进行扩展

调试和测试

以HTTP模式测试

pnpm dev:http
curl http://localhost:9001/ping

健康检查
```
curl http://localhost:9001/ping
```

🐳 运行Docker

# 빌드
pnpm build

# 이미지 빌드
docker build -t mcp-server .

# 컨테이너 실행
docker run -p 9001:9001 mcp-server

# Docker Compose 사용
docker-compose up -d

🧪 运行测试

# 모든 테스트 실행
pnpm test

# 워치 모드
pnpm test:watch

# 커버리지 포함
pnpm test:coverage

AI工具使用技巧

始终在上下文中提供相关的docs/文件
- Tool开发： #File docs/TOOL_SPEC_GUIDE.md, #File docs/MCP_SERVER.md
- 实施： #File docs/IMPLEMENTATION_GUIDE.md, #File docs/ARCHITECTURE_DIAGRAMS.md
- 测试： #File docs/TESTING_GUIDE.md
- 部署： #File docs/CONFIG_ENVIRONMENT.md, #File docs/DOCKER_GUIDE.md
强调Tool Spec First原则 -必须 #File docs/TOOL_SPEC_GUIDE.md 参考
明确具体要求和限制 -引用每个docs文件的最佳实践
分阶段请求 -为每个步骤指定相应的docs文件

使用说明

MCP服务器Starterkit-Kiro&Claude Code开发指南

🚀 快速入门

1.克隆和设置项目

2.首选参数

3.运行服务器

🎯 核心概念

MCP（模型上下文协议）란?

Tool Spec First开发

🛠️ 使用Kiro/Claude Code开发MCP服务器

步骤0：设置Context7

步骤1：创建产品需求文档（PRD）

步骤2：创建工具规范

步骤3:实施Vertical Slice

步骤4：设置依赖注入

步骤5：创建测试（可选）

📁 项目结构

🤖 AI工具使用技巧

使用Kiro时

使用Claude Code时

📚 详细指南

必需文档

参考文档

🔧 开发工作流

添加新功能

调试和测试

🐳 运行Docker

🧪 运行测试

AI工具使用技巧

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器