
MCP API Service
A Model Context Protocol (MCP) server that interacts with system APIs, allowing users to check connections, search employees, register breakfast, and update chemical information by shifts.
README
MCP API Service
Máy chủ Model Context Protocol (MCP) để tương tác với các API hệ thống nội bộ
Kiến Trúc Hệ Thống
Tổng Quan
MCP API Service là một máy chủ trung gian hoạt động theo giao thức Model Context Protocol (MCP), giúp kết nối Claude AI với các API hệ thống nội bộ. Hệ thống này:
- Nhận lệnh từ Claude: Người dùng yêu cầu thực hiện một tác vụ thông qua Claude
- Xử lý và chuyển đổi: MCP chuyển đổi các yêu cầu từ người dùng sang định dạng API nội bộ
- Gọi API: Thực hiện cuộc gọi đến các API nội bộ
- Trả kết quả: Kết quả được định dạng và trả về Claude để hiển thị cho người dùng
Cơ Chế Hoạt Động
Máy chủ MCP hoạt động bằng cách giao tiếp qua stdio (standard input/output):
- Standard Input (stdin): Nhận yêu cầu từ Claude (ví dụ: lệnh tìm kiếm nhân viên)
- Standard Output (stdout): Trả kết quả về cho Claude (ví dụ: thông tin nhân viên tìm được)
- Standard Error (stderr): Ghi log lỗi (ví dụ: lỗi kết nối đến API)
Quy trình khi một yêu cầu được gửi:
- Claude gửi yêu cầu dạng JSON qua stdin
- MCP Server xử lý yêu cầu và gọi API thích hợp
- MCP Server trả kết quả về cho Claude qua stdout
- Claude hiển thị kết quả cho người dùng
Tính Năng (Kịch Bản)
Các kịch bản hiện có:
check_connection
- Kiểm tra kết nối tới API serversearch_employee
- Tìm kiếm nhân viên theo tên hoặc mãregister_breakfast
- Đăng ký ăn sáng cho nhân viênupdate_hoa_chat
- Cập nhật thông tin hóa chất theo cachuyen_nhan_vien_thi_cong
- Chuyển nhân viên thi công giao khoán
Thêm Kịch Bản Mới
1. Thêm Endpoint
Định nghĩa endpoint mới trong src/config.ts
:
export const CONFIG = {
// ...existing code...
TOOLS: {
// ...existing code...
TEN_NHOM_API: {
ACTION_API: '/api/services/app/TenService/TenAction'
}
}
}
2. Thêm Interface
Tạo interface trong src/types.ts
cho dữ liệu đầu vào/đầu ra:
export interface TenActionInput {
Param1: string;
Param2: number;
// Các tham số khác...
}
3. Tạo Service Mới hoặc Thêm Vào Service Hiện Có
Tạo file mới trong src/services/
hoặc thêm vào service hiện có:
// src/services/ten-service.service.ts
import { TenActionInput } from '../types.js';
import { ApiClient } from '../utils/api-client.js';
import { Logger } from '../utils/logger.js';
import { CONFIG } from '../config.js';
export class TenService {
private logger = new Logger();
async tenAction(input: TenActionInput) {
try {
this.logger.debug('Calling ten action API', {
url: CONFIG.TOOLS.TEN_NHOM_API.ACTION_API,
input
});
const response = await ApiClient.post(
CONFIG.TOOLS.TEN_NHOM_API.ACTION_API,
null,
{ params: input }
);
this.logger.info('Action completed successfully', { input });
return response.result;
} catch (error) {
this.logger.error('Error performing action', { error, input });
throw error;
}
}
}
4. Cập Nhật Index
Trong src/index.ts
:
- Thêm service mới (nếu có)
- Định nghĩa tool mới trong danh sách tools
- Thêm case xử lý trong hàm handleToolCall
Phát Triển
Cài đặt thư viện:
npm install
Build server:
npm run build
Chạy chế độ phát triển với tự động build lại:
npm run watch
Gỡ Lỗi
Thách Thức
Việc gỡ lỗi MCP gặp khó khăn vì:
- Không thể đặt breakpoint như ứng dụng thông thường
- Khó theo dõi luồng dữ liệu vào/ra
- Log lỗi có thể bị trộn lẫn với output
Giải Pháp
Sử dụng MCP Inspector để:
- Theo dõi yêu cầu gửi đến máy chủ
- Xem kết quả trả về của từng yêu cầu
- Kiểm tra log lỗi riêng biệt
- Giám sát hiệu năng
Khởi động Inspector:
npm run inspector
Inspector sẽ cung cấp URL truy cập giao diện web để theo dõi hoạt động của hệ thống.
Best Practices
-
Nhất Quán
- Tuân thủ cấu trúc đặt tên hiện có
- Sử dụng mẫu code đã được thiết lập
-
Xử Lý Lỗi
- Luôn implement try/catch
- Log đầy đủ thông tin lỗi
- Trả về thông báo lỗi rõ ràng
-
Logging
- Log đầy đủ các bước: debug trước khi gọi API, info khi thành công
- Bao gồm đầy đủ parameters trong log
-
Validation
- Kiểm tra tham số bắt buộc
- Validate kiểu dữ liệu của input
Xem thêm chi tiết trong docs/add-new-scenario.md
.
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

E2B
Using MCP to run code via e2b.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.