이 프로젝트는 AI 어시스턴트를 ReviewWebsite.com API에 연결하여 웹사이트 리뷰를 생성 및 관리하고, 데이터를 추출하고, URL을 마크다운으로 변환하는 등의 작업을 수행하는 MCP(Model Context Protocol) 서버를 제공합니다.
사용 가능한 기능
- [x] 웹사이트 리뷰 생성, 읽기, 업데이트 및 삭제
- [x] 사용 가능한 AI 모델 가져오기
- [x] AI를 사용하여 URL을 마크다운으로 변환
- [x] AI를 사용하여 URL에서 구조화된 데이터 추출
- [x] URL 스크래핑 및 콘텐츠 추출
- [x] 웹사이트에서 링크 추출
- [x] AI를 활용한 URL 및 웹사이트 요약
- [x] AI 모델 및 매개변수 사용자 정의
- [x] 대기 동작 및 타이밍 제어
리뷰웹사이트
지원되는 전송
사용 방법
CLI
지엑스피1
MCP 설정
stdio 전송을 통한 로컬 구성의 경우:
{
"mcpServers": {
"reviewwebsite": {
"command": "node",
"args": ["/path/to/reviewwebsite-mcp-server/dist/index.js"],
"transportType": "stdio"
}
}
}
원격 HTTP 구성의 경우:
{
"mcpServers": {
"reviewwebsite": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
HTTP 전송을 위한 환경 변수:
다음 환경 변수를 사용하여 HTTP 서버를 구성할 수 있습니다.
MCP_HTTP_HOST : 바인딩할 호스트(기본값: 127.0.0.1 )MCP_HTTP_PORT : 수신할 포트(기본값: 8080 )MCP_HTTP_PATH : 엔드포인트 경로(기본값: /mcp )
소스 코드 개요
MCP란 무엇인가요?
MCP(Model Context Protocol)는 AI 시스템이 외부 도구 및 데이터 소스와 안전하고 상황에 맞게 연결할 수 있도록 하는 개방형 표준입니다.
이 보일러플레이트는 모든 API나 데이터 소스에 대한 사용자 정의 MCP 서버를 구축하기 위해 확장 가능한 깔끔하고 계층화된 아키텍처로 MCP 사양을 구현합니다.
왜 이 보일러플레이트를 사용해야 하나요?
- 프로덕션 준비 아키텍처 : CLI, 도구, 컨트롤러 및 서비스를 명확하게 구분하여 게시된 MCP 서버에서 사용되는 것과 동일한 패턴을 따릅니다.
- 유형 안전성 : 개발자 경험, 코드 품질, 유지 관리 용이성을 개선하기 위해 TypeScript로 구축되었습니다.
- 실제 예제 : CLI에서 API 통합까지의 전체 패턴을 보여주는 완전히 구현된 IP 조회 도구가 포함되어 있습니다.
- 테스트 프레임워크 : 커버리지 보고를 포함하여 단위 및 CLI 통합 테스트를 위한 테스트 인프라가 제공됩니다.
- 개발 도구 : MCP 서버 개발을 위해 사전 구성된 ESLint, Prettier, TypeScript 및 기타 고품질 도구가 포함되어 있습니다.
시작하기
필수 조건
- Node.js (>=18.x): 다운로드
- Git : 버전 제어를 위해
1단계: 복제 및 설치
# Clone the repository
git clone https://github.com/mrgoonie/reviewwebsite-mcp-server.git
cd reviewwebsite-mcp-server
# Install dependencies
npm install
2단계: 개발 서버 실행
stdio 전송(기본값)을 사용하여 개발 모드로 서버를 시작합니다.
또는 Streamable HTTP 전송을 사용하면:
이렇게 하면 핫 리로딩으로 MCP 서버가 시작되고 http://localhost:5173 에서 MCP 검사기가 활성화됩니다.
⚙️ 포트 6277에서 수신 중인 프록시 서버 🔍 MCP Inspector가 http://127.0.0.1:6274 에서 실행 중입니다.
HTTP 전송을 사용하는 경우 서버는 기본적으로 http://127.0.0.1:8080/mcp 에서 사용할 수 있습니다.
3단계: ReviewWebsite API 도구 테스트
CLI를 통해 ReviewWebsite API 도구를 사용하세요.
# Get available AI models
npm run dev:cli -- get-ai-models --api-key "your-api-key"
# Create a review
npm run dev:cli -- create-review --url "https://example.com" --instructions "Review this website" --api-key "your-api-key"
# Convert URL to Markdown
npm run dev:cli -- convert-to-markdown --url "https://example.com" --model "gpt-4o" --api-key "your-api-key"
건축학
이 보일러플레이트는 관심사를 분리하고 유지 관리를 용이하게 하는 깔끔하고 계층화된 아키텍처 패턴을 따릅니다.
프로젝트 구조
src/
├── cli/ # Command-line interfaces
├── controllers/ # Business logic
├── resources/ # MCP resources: expose data and content from your servers to LLMs
├── services/ # External API interactions
├── tools/ # MCP tool definitions
├── types/ # Type definitions
├── utils/ # Shared utilities
└── index.ts # Entry point
계층 및 책임
CLI 계층( src/cli/*.cli.ts )
- 목적 : 인수를 구문 분석하고 컨트롤러를 호출하는 명령줄 인터페이스를 정의합니다.
- 이름 지정 : 파일 이름은
<feature>.cli.ts 여야 합니다. - 테스트 :
<feature>.cli.test.ts 의 CLI 통합 테스트
- 목적 : AI 어시스턴트에 대한 스키마와 설명을 포함하는 MCP 도구 정의
- 이름 지정 : 파일 이름은
<feature>.tool.ts 이고 유형은 <feature>.types.ts 입니다. - 패턴 : 각 도구는 인수 검증을 위해 zod를 사용해야 합니다.
컨트롤러 레이어( src/controllers/*.controller.ts )
- 목적 : 비즈니스 로직 구현, 오류 처리 및 응답 형식 지정
- 이름 지정 : 파일 이름은
<feature>.controller.ts 여야 합니다. - 패턴 : 표준화된
ControllerResponse 객체를 반환해야 함
서비스 계층( src/services/*.service.ts )
- 목적 : 외부 API 또는 데이터 소스와 상호 작용
- 이름 지정 : 파일 이름은
<feature>.service.ts 여야 합니다. - 패턴 : 최소한의 논리를 갖춘 순수 API 상호 작용
유틸리티 레이어( src/utils/*.util.ts )
- 목적 : 애플리케이션 전반에 걸쳐 공유 기능 제공
- 주요 유틸리티 :
logger.util.ts : 구조화된 로깅error.util.ts : 오류 처리 및 표준화formatter.util.ts : 마크다운 서식 도우미
개발 가이드
개발 스크립트
# Start server in development mode (hot-reload & inspector)
npm run dev:server
# Run CLI in development mode
npm run dev:cli -- [command] [args]
# Build the project
npm run build
# Start server in production mode
npm run start:server
# Run CLI in production mode
npm run start:cli -- [command] [args]
테스트
# Run all tests
npm test
# Run specific tests
npm test -- src/path/to/test.ts
# Generate test coverage report
npm run test:coverage
코드 품질
# Lint code
npm run lint
# Format code with Prettier
npm run format
# Check types
npm run typecheck
사용자 정의 도구 구축
서버에 자신의 도구를 추가하려면 다음 단계를 따르세요.
1. 서비스 계층 정의
외부 API와 상호 작용하려면 src/services/ 에 새 서비스를 만드세요.
// src/services/example.service.ts
import { Logger } from '../utils/logger.util.js';
const logger = Logger.forContext('services/example.service.ts');
export async function getData(param: string): Promise<any> {
logger.debug('Getting data', { param });
// API interaction code here
return { result: 'example data' };
}
2. 컨트롤러 생성
비즈니스 로직을 처리하기 위해 src/controllers/ 에 컨트롤러를 추가합니다.
// src/controllers/example.controller.ts
import { Logger } from '../utils/logger.util.js';
import * as exampleService from '../services/example.service.js';
import { formatMarkdown } from '../utils/formatter.util.js';
import { handleControllerError } from '../utils/error-handler.util.js';
import { ControllerResponse } from '../types/common.types.js';
const logger = Logger.forContext('controllers/example.controller.ts');
export interface GetDataOptions {
param?: string;
}
export async function getData(
options: GetDataOptions = {},
): Promise<ControllerResponse> {
try {
logger.debug('Getting data with options', options);
const data = await exampleService.getData(options.param || 'default');
const content = formatMarkdown(data);
return { content };
} catch (error) {
throw handleControllerError(error, {
entityType: 'ExampleData',
operation: 'getData',
source: 'controllers/example.controller.ts',
});
}
}
3. MCP 도구 구현
src/tools/ 에 도구 정의를 생성합니다.
// src/tools/example.tool.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';
import { Logger } from '../utils/logger.util.js';
import { formatErrorForMcpTool } from '../utils/error.util.js';
import * as exampleController from '../controllers/example.controller.js';
const logger = Logger.forContext('tools/example.tool.ts');
const GetDataArgs = z.object({
param: z.string().optional().describe('Optional parameter'),
});
type GetDataArgsType = z.infer<typeof GetDataArgs>;
async function handleGetData(args: GetDataArgsType) {
try {
logger.debug('Tool get_data called', args);
const result = await exampleController.getData({
param: args.param,
});
return {
content: [{ type: 'text' as const, text: result.content }],
};
} catch (error) {
logger.error('Tool get_data failed', error);
return formatErrorForMcpTool(error);
}
}
export function register(server: McpServer) {
server.tool(
'get_data',
`Gets data from the example API, optionally using \`param\`.
Use this to fetch example data. Returns formatted data as Markdown.`,
GetDataArgs.shape,
handleGetData,
);
}
4. CLI 지원 추가
src/cli/ 에 CLI 명령을 생성합니다.
// src/cli/example.cli.ts
import { program } from 'commander';
import { Logger } from '../utils/logger.util.js';
import * as exampleController from '../controllers/example.controller.js';
import { handleCliError } from '../utils/error-handler.util.js';
const logger = Logger.forContext('cli/example.cli.ts');
program
.command('get-data')
.description('Get example data')
.option('--param <value>', 'Optional parameter')
.action(async (options) => {
try {
logger.debug('CLI get-data called', options);
const result = await exampleController.getData({
param: options.param,
});
console.log(result.content);
} catch (error) {
handleCliError(error);
}
});
5. 구성 요소 등록
새 구성 요소를 등록하려면 진입점을 업데이트하세요.
// In src/cli/index.ts
import '../cli/example.cli.js';
// In src/index.ts (for the tool)
import exampleTool from './tools/example.tool.js';
// Then in registerTools function:
exampleTool.register(server);
디버깅 도구
MCP 검사관
시각적 MCP 검사기에 액세스하여 도구를 테스트하고 요청/응답 세부 정보를 확인하세요.
npm run dev:server- 브라우저에서 http://localhost:5173을 엽니다.
- UI에서 직접 도구를 테스트하고 로그를 확인하세요
서버 로그
개발을 위한 디버그 로그 활성화:
# Set environment variable
DEBUG=true npm run dev:server
# Or configure in ~/.mcp/configs.json
MCP 서버 게시
사용자 정의 MCP 서버를 게시할 준비가 되면:
- package.json을 귀하의 세부 정보로 업데이트하세요
- 도구 설명서로 README.md를 업데이트하세요.
- 프로젝트 빌드:
npm run build - 프로덕션 빌드 테스트:
npm run start:server - npm에 게시:
npm publish
특허
MIT 라이센스
{
"reviewwebsite": {
"environments": {
"DEBUG": "true",
"REVIEWWEBSITE_API_KEY": "your-api-key-here"
}
}
}
참고: 이전 버전과의 호환성을 위해, 서버는 reviewwebsite 키가 없는 경우 전체 패키지 이름( reviewwebsite-mcp-server ) 또는 범위가 지정되지 않은 패키지 이름( reviewwebsite-mcp-server )의 구성도 인식합니다. 하지만 새로운 구성에는 짧은 reviewwebsite 키를 사용하는 것이 좋습니다.