AI Solution Architecture

Deep Dives

View source

Model Context Protocol Servers - Ghi chú kiến trúc

Tóm tắt điều hành

github-repos/06-tooling-mcp-ai-platform/servers là tập hợp các server tham chiếu cho Model Context Protocol. Repo được tổ chức như một monorepo gồm các package TypeScript và Python, mỗi package minh họa một vai trò MCP riêng: kiểm thử tính tương thích, truy cập filesystem, lấy nội dung web, thao tác Git, bộ nhớ dạng knowledge graph, suy luận theo bước và tiện ích múi giờ.

Repo này nên được xem là tài sản học tập và tham chiếu, không phải nền tảng đã harden cho production. README.md cấp cao nêu rõ các server này mang tính giáo dục/reference. Giá trị kiến trúc chính là repo cho thấy nhiều kiểu tương tác MCP cạnh nhau: stdio, SSE, Streamable HTTP, roots, tools, resources, prompts, notifications, structured output, task-like behavior, sampling và elicitation.

Vấn đề được giải quyết

MCP client cần server thực tế để kiểm tra primitive của giao thức từ đầu đến cuối. Repo này giải quyết nhu cầu đó bằng cách cung cấp:

Nói ngắn gọn, repo biến đặc tả MCP thành các ví dụ nhỏ, có thể chạy, đọc và mở rộng.

Vai trò trong AI stack

Các server này không host model. Chúng nằm giữa MCP client hoặc agent runtime và các hệ thống cung cấp ngữ cảnh/hành động. Client có thể cho model gọi các capability này để đọc file, lấy web content, truy vấn memory, thao tác Git hoặc tra cứu thời gian.

flowchart LR User["Người dùng / operator"] --> Client["MCP client<br/>Claude Desktop, IDE, agent runtime"] Client --> Transport["MCP transport<br/>stdio, SSE, Streamable HTTP"] Transport --> Everything["everything<br/>bao phủ giao thức"] Transport --> Filesystem["filesystem<br/>allowed directories + roots"] Transport --> Fetch["fetch<br/>web retrieval"] Transport --> Git["git<br/>repo operations"] Transport --> Memory["memory<br/>knowledge graph JSONL"] Transport --> Sequential["sequentialthinking<br/>thought history"] Transport --> Time["time<br/>timezone tools"] Filesystem --> LocalDisk["Đĩa cục bộ"] Git --> Repo["Git repository"] Fetch --> Web["HTTP sites + robots.txt"] Memory --> MemoryFile["memory.jsonl"] Time --> TZ["IANA timezone database"]

Bản đồ cây nguồn

Đường dẫnVai trò
README.mdTổng quan repo, danh sách server tham chiếu được duy trì, ví dụ cấu hình client và cảnh báo reference-only.
package.jsonNode workspace private cho các package TypeScript trong src/*.
.mcp.jsonCấu hình MCP docs server cục bộ trỏ tới endpoint tài liệu MCP công khai.
ADDITIONAL.mdDanh sách hệ sinh thái: framework, server bên thứ ba, client và tài nguyên cộng đồng.
src/everythingServer TypeScript để kiểm thử/học MCP: tools, prompts, resources, subscriptions, tasks, sampling, elicitation và nhiều transport.
src/filesystemServer TypeScript cho truy cập filesystem có kiểm soát, path validation, roots, structured output và edit helper.
src/memoryServer TypeScript lưu knowledge graph bằng JSONL.
src/sequentialthinkingServer TypeScript ghi nhận suy luận theo bước, branch/revision và tùy chọn tắt log.
src/fetchServer Python lấy nội dung web bằng HTTPX, readability extraction, markdown conversion và robots.txt.
src/gitServer Python dùng GitPython, có giới hạn repository và annotation cho thao tác đọc/ghi/nguy hiểm.
src/timeServer Python cho thời gian/múi giờ bằng IANA timezone và zoneinfo.

Khái niệm cốt lõi

Primitive của MCP

Repo này minh họa các primitive chính của MCP:

Mẫu server tham chiếu

Mỗi server giữ trách nhiệm hẹp. Package tạo MCP server, đăng ký tool/resource/prompt, rồi kết nối transport. Phần lớn server dùng stdio vì đây là transport phổ biến cho desktop MCP client. Riêng everything bổ sung SSE và Streamable HTTP để client author kiểm thử session, event replay, CORS, cleanup và endpoint HTTP.

Scope do client và cấu hình kiểm soát

Một bài học lặp lại trong repo là MCP server không nên mặc định có toàn quyền trên host. filesystem cần allowed directories hoặc roots. git xác thực repository nằm trong scope cho phép. fetch tôn trọng robots.txt cho tool call tự động, trừ khi operator chủ động bỏ qua. Đây chưa phải hardening production, nhưng thể hiện đúng hướng least privilege.

Kiến trúc nội bộ

Dạng monorepo

Node workspace ở root bao phủ các server TypeScript. Các server Python như fetch, gittime là project độc lập có pyproject.toml riêng. Không có runtime dùng chung cho toàn bộ repo; mỗi server là một tiến trình/capability độc lập.

Kiến trúc theo server

src/everything

src/filesystem

src/memory

src/sequentialthinking

src/fetch

src/git

src/time

Luồng end-to-end

Sơ đồ dưới mô tả đường stdio phổ biến. Với HTTP, server có thêm session management và routing endpoint, nhưng mô hình handler vẫn tương tự.

sequenceDiagram participant User as Người dùng participant Client as MCP client participant Server as Tiến trình server tham chiếu participant Handler as Handler tool/resource/prompt participant System as Hệ thống cục bộ hoặc bên ngoài User->>Client: Yêu cầu ngữ cảnh hoặc hành động Client->>Server: initialize + thương lượng capability Server-->>Client: capabilities, tools, resources, prompts Client->>Server: tools/call hoặc resources/read Server->>Handler: Validate schema và policy Handler->>System: Đọc, ghi, fetch, Git, memory hoặc timezone lookup System-->>Handler: Kết quả hoặc lỗi Handler-->>Server: MCP content + structuredContent Server-->>Client: Kết quả tool, notification hoặc error Client-->>User: Câu trả lời hoặc tóm tắt hành động

Runtime và data flow

Luồng gọi tool

  1. Client khởi chạy tiến trình server hoặc kết nối HTTP endpoint.
  2. Server công bố capabilities và handler đã đăng ký.
  3. Client liệt kê tool/resource/prompt hoặc gọi trực tiếp item đã biết.
  4. Server validate input bằng SDK schema, Zod hoặc Pydantic.
  5. Handler của package thực hiện thao tác trong scope cho phép.
  6. Server trả về content block, structured data hoặc protocol error.

Trạng thái và persistence

ServerMô hình trạng thái
everythingIn-memory tasks, subscriptions, simulated updates và event replay cache.
filesystemKhông có durable state; allowed directories là runtime state và có thể đổi theo roots notification.
memoryFile graph JSONL bền vững.
sequentialthinkingThought history và branch map trong bộ nhớ của tiến trình.
fetchGần như stateless; HTTP response và robots check theo từng request.
gitState bền vững nằm trong Git repository mục tiêu.
timeStateless, suy ra từ timezone data của hệ thống.

Xử lý lỗi

Topology triển khai và vận hành

flowchart TB subgraph Desktop["Desktop / IDE runtime"] Client["MCP client"] Stdio["Tiến trình con qua stdio"] end subgraph NodeServers["Package Node.js"] Everything["mcp-server-everything"] Filesystem["mcp-server-filesystem"] Memory["mcp-server-memory"] Sequential["mcp-server-sequential-thinking"] end subgraph PythonServers["Package Python"] Fetch["mcp-server-fetch"] Git["mcp-server-git"] Time["mcp-server-time"] end subgraph HostSystems["Host và hệ thống ngoài"] Disk["Thư mục được phép"] Repo["Git repo được phép"] MemoryJsonl["memory.jsonl"] Internet["Web target"] TzDb["Timezone database"] end Client --> Stdio Stdio --> Everything Stdio --> Filesystem Stdio --> Memory Stdio --> Sequential Stdio --> Fetch Stdio --> Git Stdio --> Time Everything -. tùy chọn .-> Http["SSE / Streamable HTTP<br/>PORT hoặc 3001"] Filesystem --> Disk Memory --> MemoryJsonl Fetch --> Internet Git --> Repo Time --> TzDb

Điểm mở rộng

Thêm hoặc sửa server TypeScript

Pattern hiện có là tạo src/<server> với:

everything là tài liệu sống cho tính năng giao thức nâng cao. filesystem là ví dụ tốt nhất về truy cập hệ thống cục bộ có phòng vệ.

Thêm hoặc sửa server Python

Pattern trong fetch, gittime gồm:

Bài học thiết kế tool

Tích hợp

Các tích hợp chính:

Cấu hình, triển khai và vận hành

Hạng mụcGhi chú thực tế
TransportĐa số server dùng stdio. everything có thêm SSE cũ và Streamable HTTP.
Cổng của everythingHTTP transport đọc PORT, mặc định 3001.
Scope filesystemTruyền allowed directories qua command line hoặc dùng MCP roots. Không có scope thì initialization lỗi.
Đường dẫn memoryMEMORY_FILE_PATH ghi đè vị trí memory.jsonl.
Log suy luậnDISABLE_THOUGHT_LOGGING=true tắt formatted thought logs.
Chính sách fetchCLI flags cấu hình user agent, proxy và việc bỏ qua robots.txt cho autonomous fetch.
Scope GitKhởi động với repository rõ ràng hoặc dùng client roots; repo path được validate.
Timezonetime cho phép override local timezone và yêu cầu IANA timezone name.

Về vận hành, hãy coi mỗi server là một ranh giới capability riêng. Không nên cấp đồng thời filesystem rộng và mutating Git tools cho cùng một client nếu workflow không thật sự cần.

Observability, testing, evaluation và failure modes

Observability

Repo giữ thiết kế nhẹ. Observability chủ yếu đến từ log tiến trình, protocol response và client-side inspection:

Nếu đưa vào production, nên bọc các server bằng process supervision, log collection và audit trail cho tool có side effect.

Testing và evaluation

Repo có test tập trung:

Lượt tài liệu này không yêu cầu cài dependency hoặc chạy test.

Failure modes phổ biến

Rủi ro bảo mật và governance

Đây là repo tham chiếu, vì vậy production hardening thuộc về người áp dụng.

Rủi ro chính:

Khuyến nghị governance:

Vòng đời và sơ đồ quyết định

flowchart TD Start["Cần expose ngữ cảnh hoặc hành động cho AI client"] --> NeedType{"Capability cần là gì?"} NeedType -->|Test MCP client| Everything["Dùng everything"] NeedType -->|File cục bộ| FsScope{"Có thể scope hẹp không?"} FsScope -->|Có| Filesystem["Dùng filesystem với roots/allowed dirs"] FsScope -->|Không| RejectFs["Không expose filesystem rộng"] NeedType -->|Nội dung web| FetchPolicy{"Cho phép autonomous fetch?"} FetchPolicy -->|Tôn trọng robots| Fetch["Dùng fetch mặc định"] FetchPolicy -->|Cần override| FetchRisk["Dùng fetch với governance rõ"] NeedType -->|Git workflow| GitScope{"Repository tin cậy?"} GitScope -->|Có| Git["Dùng git server"] GitScope -->|Không| RejectGit["Tránh Git tool có side effect"] NeedType -->|Tri thức bền vững| Memory["Dùng memory JSONL graph"] NeedType -->|Trace suy luận| Seq["Dùng sequentialthinking"] NeedType -->|Múi giờ| Time["Dùng time"] Everything --> Observe["Quan sát hành vi giao thức"] Filesystem --> Observe Fetch --> Observe Git --> Observe Memory --> Observe Seq --> Observe Time --> Observe

Hướng dẫn đọc repo

Nên đọc theo thứ tự:

  1. README.md để nắm mục tiêu, danh sách server và ví dụ cấu hình client.
  2. src/everything/README.mdsrc/everything/docs/* để thấy đầy đủ primitive MCP.
  3. src/filesystem/src/lib.tssrc/filesystem/src/path-validation.ts để học local access có phòng vệ.
  4. src/fetch/src/mcp_server_fetch/server.py để hiểu web retrieval và robots policy.
  5. src/git/src/mcp_server_git/server.py để hiểu repository scoping và annotation.
  6. src/memory/index.ts, src/sequentialthinking/src/lib.ts, src/time/src/mcp_server_time/server.py để xem các ví dụ nhỏ gọn.

Lộ trình học tập

  1. Bắt đầu với time vì nó nhỏ và stateless.
  2. Đọc memory để hiểu durable state cho tool.
  3. Đọc filesystem để học validation và roots negotiation.
  4. Đọc fetch để hiểu network governance và truncate nội dung.
  5. Đọc git để so sánh tool read-only và destructive.
  6. Đọc everything sau cùng vì nó tổng hợp hầu hết bề mặt giao thức.

Bảng thuật ngữ

Thuật ngữNghĩa trong repo này
MCPModel Context Protocol, giao thức client/server mà các package implement.
ClientỨng dụng host hoặc agent runtime khởi chạy/kết nối server.
ToolThao tác có thể gọi từ client.
ResourceNội dung có URI để truy cập.
PromptMẫu prompt server trả về để tái sử dụng.
RootScope do client khai báo, thường là thư mục hoặc repository.
TransportKênh giao tiếp như stdio, SSE hoặc Streamable HTTP.
Structured contentDữ liệu machine-readable trả về cùng với nội dung cho người đọc.
AnnotationMetadata mô tả tool read-only, destructive, idempotent hay open-world.
JSONLĐịnh dạng JSON mỗi dòng một record, được memory sử dụng.

Deep Dive Bám Theo Repository

Repository này là tập hợp implementation tham chiếu cho thiết kế capability MCP. Các server TypeScript dưới github-repos/06-tooling-mcp-ai-platform/servers/src/everything/, src/filesystem/, src/memory/src/sequentialthinking/ thể hiện các mức độ capability khác nhau, trong khi server Python dưới src/fetch/, src/git/src/time/ cho thấy cách expose hệ thống bên ngoài qua tool nhỏ hơn. Bài học kiến trúc quan trọng nhất là MCP server phải được đánh giá bằng scope control, tool annotations, transport assumptions và result structure, không chỉ bằng số lượng tool.

flowchart LR Client["MCP client hoac agent host"] --> Transport["stdio, SSE, hoac Streamable HTTP"] Transport --> Server["server index.ts hoac Python server.py"] Server --> Tools["tools registration"] Server --> Resources["resources va templates"] Server --> Prompts["prompt templates"] Server --> Roots["client roots va scope"] Tools --> Fs["filesystem path validation"] Tools --> Mem["memory JSONL graph"] Tools --> Net["fetch network access"] Tools --> Git["git repository operations"] Resources --> Everything["everything reference server"]

Server everything nên được đọc như bộ exerciser cho protocol: src/everything/tools/, resources/, prompts/, transports/server/ minh họa bề rộng. Các server nhỏ mới là ví dụ production tốt hơn. src/filesystem/path-validation.ts, src/filesystem/roots-utils.tssrc/filesystem/lib.ts cho thấy filesystem access bị giới hạn bởi root. src/memory/index.ts cho thấy knowledge graph persist bằng JSONL. src/sequentialthinking/lib.ts cho thấy dữ liệu suy luận có trạng thái. Các server Python fetch, gittime cho thấy cách bind external API hoặc operation kiểu command vào MCP mà không cần service monorepo lớn.

sequenceDiagram participant Host as Agent host participant MCP as MCP server participant Guard as Scope va validation participant Impl as Tool implementation participant Ext as Filesystem, network, git, hoac time Host->>MCP: initialize va list capabilities MCP-->>Host: tools, resources, prompts, annotations Host->>MCP: call tool voi arguments MCP->>Guard: validate schema, roots, paths, va policy Guard->>Impl: approved invocation Impl->>Ext: perform scoped operation Ext-->>Impl: raw result Impl-->>MCP: content plus structured content MCP-->>Host: result hoac explicit error
flowchart TD Risk["Rui ro production MCP"] --> Scope["scope qua rong"] Risk --> Annotation["tool annotation sai"] Risk --> Transport["transport mismatch"] Risk --> Data["result thieu cau truc"] Risk --> Persistence["state file corruption"] Risk --> Network["open-world network access"] Scope --> S1["filesystem hoac git tool vuot root"] Annotation --> A1["client approve destructive tool nhu read-only"] Transport --> T1["server deploy sai lifecycle expectation"] Data --> D1["agent khong parse ket qua on dinh"] Persistence --> P1["memory graph mat entities hoac relations"] Network --> N1["fetch server truy cap host bi cam"]

Checklist Sẵn Sàng Production

Hướng Dẫn Đọc Cho Senior Architect

Đọc src/filesystem/ trước vì nó minh họa pattern production quan trọng nhất: client roots cộng với local validation. Sau đó đọc src/memory/ cho persistent state, src/sequentialthinking/ cho stateful tool data, và các package Python src/fetch/, src/git/, src/time/ cho thiết kế external operation. Kết thúc bằng src/everything/ để hiểu toàn bộ protocol surface sau khi đã rõ các safety pattern hẹp hơn.