That is the failure mode. The model is not retrieving the site. It is interpolating a site-shaped answer from training data, prior chat, and whatever fragments happened to be in the prompt. Project names drift. Metrics get rounded. Pages that never existed sound real.

The fix is not a better system prompt. It is a tool boundary: the client should only claim what a tool returned, and the tool should only return text it fetched, with the public URLs attached.

site-context-mcp is a small Python MCP server that does exactly that. It speaks MCP over stdio via FastMCP, fetches a public llms.txt plus the same-host pages it links, caches them in-process (~1 hour TTL), and exposes four tools. Every response is JSON text with a top-level sources[].

This is site/project context, not an identity server. A sibling package, resume-mcp, already answers "who is this person" from resume.json. Mixing those jobs is how you get a resume tool that starts inventing product pages.

The contract: no citation, no claim

MCP is a typed tool protocol. A local process lists tools; the model calls them; the host returns structured results. The interesting part is what you put in those results.

This server treats sources as a required field, not a nicety. A helper merges the tool body with a de-duplicated URL list and json.dumps the whole thing. Error paths do the same: an empty search query, a missing page, a failed corpus load — all still include sources. If a fetch partially fails, the surviving pages are returned and the failures show up in cache_notes.

FastMCP instructions tell the host model to answer from the cached corpus and to cite those URLs. Instructions are not enforcement. The enforcement is the payload: if the snippet is not in the tool result, it did not come from this server.

Seed from llms.txt, then same-host only

On process start the server tries cache.ensure_loaded() (and again on first tool use if that failed, or when the in-process TTL expires — CACHE_TTL_SECONDS = 3600). The cache then:

1. GETs the wired host's /llms.txt (default: https://yongbo-yu.vercel.app/llms.txt)
2. Parses markdown links in document order
3. Fetches each allowed URL
4. Always seeds home, a known /projects/... evidence page, and /resume.json if parsing is thin

Allowlisting is the security model. A URL is kept only if it is HTTPS, on the wired host, not a binary extension (images, fonts, PDFs, archives), and not a blocked fragment (off-host social, private admin hosts, internal app paths). Redirects that leave the host are dropped. There are no API keys and no cookies.

The default corpus is one public site. The shape — llms.txt as the machine-readable index, same-host follow, in-memory TTL — is the reusable part. Change the host constant to another public site that publishes llms.txt and you get the same tools.

HTML is stripped with a small html.parser.HTMLParser: skip script / style / svg / noscript, prefer main / article over the rest of body, take <title> (dropping a | Site name suffix) and meta / og:description. JSON pages are pretty-printed so keyword search can hit field values. Plain text (llms.txt) is stored as-is.

Fetch uses httpx (20s timeout, follow redirects, User-Agent site-context-mcp/0.1.0). A threading.Lock serializes reloads so two overlapping tool calls cannot double-fetch. Failures append to cache.errors instead of aborting the whole corpus — one 500 should not erase ten good pages.

Four tools, one response shape

search_site is not embeddings. It lowercases the query, splits on whitespace, scores chunks by how many tokens appear, and keeps the best snippet per page plus title/description hits. HTML is split on sentences; llms.txt / JSON use paragraph blocks. limit is clamped to 1–25 (default 8). Dedup key is source|snippet[:120].

get_project is still site context. It resolves a slug or display name to a cached /projects/... page. If resume.json was fetched, a short cross-link (name, description, up to five highlights, dates) is attached and resume.json is added to sources. It does not grow identity or resume-summary tools.

list_site_pages always puts llms.txt first in sources, then every page URL. get_page cites the page plus llms.txt. A miss returns available_paths so the model can recover without guessing.

Example — get_page("/projects/kilodock"). That path is one page in the default corpus, not the subject of this post. The tool returns JSON text shaped like:

{
  "url": "https://yongbo-yu.vercel.app/projects/kilodock",
  "path": "/projects/kilodock",
  "title": "KiloDock — Gym Operating System by YongBo Yu",
  "description": null,
  "kind": "html",
  "content_type": "text/html",
  "text": "KiloDock is a multi-tenant CrossFit gym operating system independently built by YongBo Yu. ... Mobile schedule latency: 2.84.6s down to 683ms. Admin load: six API calls / 3.05s down to one call / 778ms. ...",
  "cache_notes": null,
  "sources": [
    "https://yongbo-yu.vercel.app/projects/kilodock",
    "https://yongbo-yu.vercel.app/llms.txt"
  ]
}

search_site("LangGraph") is the more typical agent call. Each match has snippet + source; the top-level sources array is the union of llms.txt and every hit URL. The client can quote a snippet and the URL in the same breath. If cache_notes is a non-null list, a page was skipped — treat the corpus as partial, not complete.

Install and wire it into Cursor

Python 3.11+. Dependencies: mcp>=1.9,<2 and httpx. From a clone of the repo:

pip install -e ".[dev]"
pytest -q
python -m site_context_mcp

Tests mock httpx.Client; they do not need live network. CI runs pytest on 3.11 and 3.12. After install, the console script is site-context-mcp. Equivalent: uv run python -m site_context_mcp.

The process speaks MCP on stdin/stdout. Do not print logs to stdout; they corrupt the protocol. FastMCP's default transport here is stdio — that is what Cursor and Claude Desktop spawn as a child process.

Cursor (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "site-context-mcp": {
      "command": "python3",
      "args": ["-m", "site_context_mcp"],
      "cwd": "/absolute/path/to/site-context-mcp"
    }
  }
}

If the package lives in a venv, point command at that interpreter. With uv:

{
  "mcpServers": {
    "site-context-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "site_context_mcp"],
      "cwd": "/absolute/path/to/site-context-mcp"
    }
  }
}

Reload MCP servers. The four tools should appear under site-context-mcp. Then ask the client to list cached pages and cite the URLs, or to search the corpus and return snippets with sources. If the answer has no URL, it did not come from this tool.

Why this is enough (and what it is not)

This is not a crawler, not a vector store, and not a general web browser. It will not follow off-host links, will not ingest PDFs or images, and will not refresh more often than the TTL unless you restart the process (or wait out the hour). For a personal or project site that already publishes llms.txt, that is the right size: the index is the author's, the pages are public HTTPS, and the agent cannot silently mix in a different origin.

The alternative — stuffing the whole site into the system prompt — expires the moment a page changes and burns context on every turn. Caching in the MCP process keeps the corpus off the prompt until a tool call needs it. sources[] makes the citation path mechanical instead of a polite request in the system prompt.

If you already run resume-mcp for identity, run this beside it. One server for who someone is; one for what the site actually says. Keep the tool names honest, keep stdout clean, and refuse to answer a project claim that did not arrive with a URL.

YongBo Yu (also Yong Yu) · Toronto · yongbo-yu.vercel.app · github.com/YongBoYu1/site-context-mcp

Attributed Chinese → English compile
Source: [MCP][02]快速入门MCP开发
Original author: 花酒锄作田 (Cnblogs) · Posted: 2025-09-15
This is an English rewrite of the original tutorial’s ideas and code patterns. It is not original work by the compiler. Always link the Chinese source; do not present this compile as the original.

Many MCP write-ups only show how to register a Server and paste it into Cursor. The Cnblogs post by 花锄作田 is useful for product engineers because it also builds the Client / Host side: list prompts, resources, and tools; call them over stdio; switch to streamable HTTP; then let an LLM decide which tool to invoke.

If you are shipping agents into a backend, that Client loop is the missing middle between “SDK demo and “our service owns the tool session.” You need a reliable discover → bind → call → feed-back loop before you care which model sits on top.

Environment

The author used Python 3.13.5 (3.11+ is fine). Prefer uv or pip:

# uv
uv add mcp fastmcp

# or pip
python -m pip install mcp fastmcp

Notes from the source:

• The official mcp package ships FastMCP v1; community FastMCP has moved to v2—trying both while learning is fine.
• Write type hints, return types, and docstrings carefully. Those become the model-facing tool descriptions later.

Step 1 — Minimal FastMCP Server (stdio)

Concept: prompts, resources, and tools on one server with transport="stdio".

Illustrative shape (adapted from the original). Trim any SSH / remote-shell tools before you run this locally unless you harden them first:

from datetime import datetime
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("custom")

@mcp.prompt()
def greet_user(name: str, style: str = "formal") -> str:
    """Greet a user with a specified style."""
    if style == "friendly":
        return f"Hey {name}! What's up?"
    return f"Hello, {name}!"

@mcp.resource("greeting://{name}")
def greeting_resource(name: str) -> str:
    """A simple greeting resource."""
    return f"Hello, {name}!"

@mcp.resource("config://app")
def get_config() -> str:
    """Static configuration data"""
    return "App configuration here"

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.tool()
async def get_date() -> str:
    """Get today's date."""
    return datetime.now().strftime("%Y-%m-%d")

@mcp.tool()
async def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")

Preflight: run the server script alone once. If imports fail, the Client will fail in a confusing way when it tries to spawn the child process.

Production caution — SSH / god-mode shell: the original also demonstrates a remote SSH tool. Treat that as high-risk. Do not expose arbitrary remote command execution to a model without allowlists, authentication, and human confirmation. Prefer narrow, typed tools over “run anything on this host.”

Step 2 — Stdio Client with ClientSession

The Client launches the Server as a subprocess via StdioServerParameters (absolute interpreter, script path, and cwd). Pattern from the source:

import asyncio
from pathlib import Path
from pydantic import AnyUrl

from mcp import ClientSession, StdioServerParameters, types
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command=str(Path(__file__).parent / ".venv" / "bin" / "python"),
    args=[str(Path(__file__).parent / "demo1-server.py")],
    cwd=str(Path(__file__).parent),
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            prompts = await session.list_prompts()
            print([p.name for p in prompts.prompts])

            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            resource_content = await session.read_resource(AnyUrl("greeting://World"))
            block = resource_content.contents[0]
            if isinstance(block, types.TextResourceContents):
                print(block.text)

            result = await session.call_tool("add", arguments={"a": 5, "b": 3})
            print(result.content[0].text if result.content else result)
            print(result.structuredContent)

if __name__ == "__main__":
    asyncio.run(run())

Expected behavior (as reported in the original run): prompts listed, resource text returned, add yields 8 plus structured content.

Failure mode to remember: starting the Client also starts the Server. Server syntax or import errors look like Client connection failures—debug the Server first.

Step 3 — Same Server over streamable-http

Server change:

mcp = FastMCP("custom", host="localhost", port=8001)

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Client change (conceptually): use streamablehttp_client("http://localhost:8001/mcp"), then the same ClientSession.initialize() / list_* / call_tool flow. The source notes a third return value, get_session_id, for session managementusually unused in hello-worlds.

This is the fork most product backends care about: stdio for desktop or host-local tools, HTTP for remotely deployed tool servers.

Docs and ecosystem starting points:

• MCP Python SDK / quickstart
• FastMCP docs (community) for transport options

Step 4 — Let the LLM choose tools

Server stays the same. Client:

1. Connect (HTTP example in the post).
2. Call list_tools() and map each tool to an OpenAI-compatible function schema (name, description, parameters from inputSchema).
3. Call chat completions with tools=....
4. While the model emits tool calls: session.call_tool(name, args), append assistant and tool messages, call the model again.
5. Stop when there are no more tool calls.

The original uses an OpenAI-compatible client pointed at Qwen / DashScope (qwen-plus, compatible-mode/v1). Any OpenAI-tools-compatible endpoint works the same way (DeepSeek, OpenAI, and similar).

Config sketch from the source’s supplementary modules:

{
  "llm": {
    "model": "qwen-plus",
    "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "your token"
  },
  "server": {
    "host": "127.0.0.1",
    "port": 8000
  }
}

Example interactive outcomes from the original session:

• “What is todays date?” → get_date
• “Weather in Hefei?” → get_weather with {city: ""}
• Numeric compare → custom comparison tool

That is the whole product loop in miniature: discover → bind schemas model proposes → your code executes feed results back.

Logging pitfall while integrating the LLM

The author’s sample logger can write to a file; if you stream-log, keep protocol traffic on the MCP pipes and human logs elsewhere. Mixing debug prints into a stdio Server’s stdout will break JSON-RPC—the same lesson every serious MCP guide repeats.

Why this matters for agents / MCP / RAG products

Shipping an LLM feature is less about a single chat completion and more about a reliable tool session: spawn or connect to servers, refresh schemas, bound the agent loop, and keep transports swappable (local stdio versus remote HTTP). The same Client you use for MCP tools is where you later hang RAG retrieval as a resource or tool—without rewriting the host when you add the next capability. Get this loop solid once, and every new tool becomes a schema change instead of a host rewrite.

Compiler (not original author)

English compile by YongBo Yu.
https://yongbo-yu.vercel.app · https://github.com/YongBoYu1

Original Chinese article © 花酒锄作田 / Cnblogs. Always link the source; do not present this compile as the original.

Attributed Chinese → English compile
Source: MCP Server 实战：从协议到本地工具调用
Original author: AJie (AJie's Blog) · Published: 2026-06-03
This is a faithful English rewrite for learning. It is not original research by the compiler. Always link the Chinese original; do not present this compile as the source work.

Most first MCP tutorials jump straight to “register a tool, wire stdio, celebrate the demo.” AJie’s post is useful because it starts one layer earlier: an MCP Server is a capability boundary, not a dumping ground for whatever the model might want to run on your machine.

AJie’s practical rule: if the model must understand intent and the tool should do deterministic work, make an MCP tool. If the work itself still needs open-ended judgment (“rewrite this article”), leave that to the model and only give it evidence tools.

Scenario: project analysis without “give me shell”

Instead of exposing a generic shell, split a local project-assistant into narrow tools:

Design I/O so the model guesses less

Tool descriptions are routing context for the model, not human README fluff.

Weak:

Read a file from local project.

Stronger (paraphrased from the source’s guidance):

Read a text file under the configured project root. Use when you need a specific source, markdown, or config file. Path must be relative to project root. Optional start / limit restrict the returned line range.

Suggested parameters for read_project_file:

• path (string): relative to project root
• start (number): start line
• limit (number): max lines

Suggested structured return:

1. The user configures a launch command in the host (Claude Desktop, Claude Code, Cursor, or your own host).
2. The client starts a local server process.
3. The server waits on stdio for initialize.
4. The client lists tools.
5. The model decides whether to call.
6. The client forwards tools/call.
7. The server runs the local capability and returns JSON-RPC over stdout.

Troubleshooting map (from the source)

Hard rule for stdio: never write casual debug logs to stdout. Stdout is the protocol channel. Use stderr or a log file. AJie recommends a tiny ping_project tool first: accept a string; return project name, cwd, and the echoed input. You are not proving business value—you are proving:

• The client can spawn the server
• Initialize completes
• The tool appears in the list
• Args round-trip
• The response renders in the host
• stderr does not corrupt the protocol

Then add one real tool at a time and call it from the host after each addition. When something breaks, the last delta is obvious.

Many “works locally, fails in Claude Code” issues are path, env, or cwd mismatches—not SDK bugs.

Safety tiers before you expose writes

Do not accept arbitrary absolute paths. Do not ship “run any shell command” as a general tool. Prefer allowlisted roots such as reports/ or drafts/. Example failure shape (paraphrased): instead of bare ENOENT, return file_not_found plus a hint to call list_project_files first. That turns a retry loop into a recovery path.

Rollout checklist for a real project

1. Pick one narrow scenario (one sentence).
2. Split two or three read-only tools with clear I/O.
3. Prove the stdio minimum loop in the target host.
4. Connect real data with truncated, structured returns.
5. Add recoverable error objects.
6. Guard context budget (paginate or summarize).
7. Only then consider writes with directory and confirmation gates.

Why this matters if you are shipping agents / MCP into a product

Product agents fail less often on “model IQ” than on tool surface area: over-broad tools, polluted stdio, and unrecoverable errors. MCP gives you a standard discovery and call pipe; you still have to design the boundary as carefully as a public API. Pair this with RAG the same way—retrieve evidence as structured resources, execute side effects as narrow tools, and keep both behind server-side policy. That is the difference between a demo that works once and a capability you can operate.

Compiler (not original author)

English compile by YongBo Yu.
Site: https://yongbo-yu.vercel.app · GitHub: https://github.com/YongBoYu1

Original post remains © AJie / source site. Read the Chinese original before publishing any derivative.

Debug order that actually works

1. Run the server start command alone.
2. Verify initialize with the ping tool.
3. Capture model-supplied args versus the schema.
4. Cap output length.
5. Return structured errors (ok, error, message, path, hint).
6. Only then attach real files, APIs, or commands.

Official references the source points at:

• Model Context Protocol docs
• MCP TypeScript SDK
• Host docs for your target client (Claude Code, Cursor, etc.)

Ship a minimum closed loop before real tools

• path, start, end, content, truncated

Truncation and pagination beat dumping tens of thousands of lines into the context window. MCP Servers should default to summaries, slices, or pages.

The stdio call chain (local MCP’s default path)

Local MCP almost always means:

file types | path list | Scope the workspace | | read_project_file | relative path, line range | snippet | Pull only needed context | | summarize_markdown_posts | directory, limit | title / date / summary table | Inventory content | | find_internal_links | path | in-page links | Structure checks | | check_frontmatter | path | missing / bad fields | Pre-publish lint |

If you are wiring agents, MCP, or RAG into a product, that framing matters. Models do not “use your laptop”; they generate call intents against schemas. Your job is to expose narrow, typed, recoverable actions—and keep stdout clean so the JSON-RPC pipe does not die under log noise. Over-broad tools and silent protocol corruption show up as “the agent is flaky,” when the real failure is the tool surface.

What a good tool boundary looks like