Этот проект предоставляет сервер Model Context Protocol (MCP), который подключает помощников на основе искусственного интеллекта к API ReviewWebsite.com для создания и управления обзорами веб-сайтов, извлечения данных, преобразования URL-адресов в разметку и многого другого.
Доступные функции
- [x] Создание, чтение, обновление и удаление обзоров веб-сайтов
- [x] Получить доступные модели ИИ
- [x] Преобразование URL-адресов в Markdown с помощью ИИ
- [x] Извлечение структурированных данных из URL-адресов с помощью ИИ
- [x] Собирайте URL-адреса и извлекайте содержимое
- [x] Извлечение ссылок с веб-сайтов
- [x] Обобщение URL-адресов и веб-сайтов с помощью ИИ
- [x] Настройка моделей и параметров ИИ
- [x] Управление поведением и временем ожидания
ОбзорWeb.site
Поддерживаемые транспорты
- [x] "stdio" transport — транспорт по умолчанию для использования CLI
- [x] Транспорт«Streamable HTTP» — для веб-клиентов
- [ ] Реализовать аутентификацию (заголовки «Authorization» с
Bearer <token> )
- [ ]
"sse" транспорт (Устаревшее) - [ ] Написать тесты
Как использовать
CLI
# Get available AI models
npm run dev:cli -- get-ai-models --api-key "your-api-key"
# Create a new review
npm run dev:cli -- create-review --url "https://example.com" --instructions "Review this website" --api-key "your-api-key"
# Get a specific review by ID
npm run dev:cli -- get-review --review-id "review-id" --api-key "your-api-key"
# List all reviews
npm run dev:cli -- list-reviews --page 1 --limit 10 --api-key "your-api-key"
# Update a review
npm run dev:cli -- update-review --review-id "review-id" --url "https://example.com" --instructions "Updated instructions" --api-key "your-api-key"
# Delete a review
npm run dev:cli -- delete-review --review-id "review-id" --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"
# Extract structured data from URL
npm run dev:cli -- extract-data --url "https://example.com" --instructions "Extract product information" --api-key "your-api-key"
# Scrape URL
npm run dev:cli -- scrape-url --url "https://example.com" --api-key "your-api-key"
# Extract links from URL
npm run dev:cli -- extract-links --url "https://example.com" --type "all" --api-key "your-api-key"
# Summarize URL
npm run dev:cli -- summarize-url --url "https://example.com" --model "gpt-4o" --api-key "your-api-key"
Настройка МКП
Для локальной конфигурации с транспортом 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 )
Обзор исходного кода
Что такое МКП?
Model Context Protocol (MCP) — открытый стандарт, позволяющий системам искусственного интеллекта безопасно и контекстно подключаться к внешним инструментам и источникам данных.
Этот шаблон реализует спецификацию MCP с помощью чистой многоуровневой архитектуры, которую можно расширить для создания пользовательских серверов MCP для любого API или источника данных.
Зачем использовать этот шаблон?
- Архитектура, готовая к производству : следует той же схеме, которая используется в опубликованных серверах MCP, с четким разделением между CLI, инструментами, контроллерами и службами.
- Безопасность типов : создано с использованием TypeScript для улучшения опыта разработки, качества кода и удобства обслуживания.
- Рабочий пример : включает в себя полностью реализованный инструмент поиска IP-адресов, демонстрирующий полную модель от CLI до интеграции API.
- Тестовая среда : поставляется с тестовой инфраструктурой для модульных и интеграционных тестов CLI, включая отчеты о покрытии.
- Инструменты разработки : включают ESLint, Prettier, TypeScript и другие качественные инструменты, предварительно настроенные для разработки сервера MCP.
Начиная
Предпосылки
- 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 (по умолчанию):
Или с помощью потокового HTTP-транспорта:
Это запустит сервер MCP с горячей перезагрузкой и включит MCP Inspector по адресу http://localhost:5173 .
⚙️ Прокси-сервер прослушивает порт 6277 🔍 MCP Inspector запущен и работает по адресу http://127.0.0.1:6274
При использовании HTTP-транспорта сервер по умолчанию будет доступен по адресу http://127.0.0.1:8080/mcp .
Шаг 3: Тестирование API-инструментов ReviewWebsite
Используйте инструменты API ReviewWebsite через CLI:
# 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 - Тестирование : тесты интеграции CLI в
<feature>.cli.test.ts
- Цель : Определить инструменты 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 : Помощники форматирования Markdown
Руководство по разработке
Сценарии разработки
# 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. Определите уровень обслуживания
Создайте новую службу в src/services/ для взаимодействия с вашим внешним API:
// 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
Создайте команду CLI в src/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, чтобы протестировать свои инструменты и просмотреть сведения о запросах/ответах:
- Запустите
npm run dev:server - Откройте http://localhost:5173 в вашем браузере.
- Тестируйте свои инструменты и просматривайте журналы прямо в пользовательском интерфейсе
Журналы сервера
Включить журналы отладки для разработки:
# 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
Лицензия
Лицензия Массачусетского технологического института
{
"reviewwebsite": {
"environments": {
"DEBUG": "true",
"REVIEWWEBSITE_API_KEY": "your-api-key-here"
}
}
}
Примечание: Для обратной совместимости сервер также распознает конфигурации под полным именем пакета ( reviewwebsite-mcp-server ) или именем пакета без области действия ( reviewwebsite-mcp-server ), если ключ reviewwebsite не найден. Однако для новых конфигураций рекомендуется использовать короткий ключ reviewwebsite .