How to build an MCP server in Python

uv init --python 3.11 text-tools && cd text-tools
uv add "mcp[cli]>=2.0.0"

"""A minimal, tested MCP server in Python using the official SDK (mcp 2.0)."""
from typing import TypedDict

from mcp.server.mcpserver import MCPServer

mcp = MCPServer(name="text-tools", version="1.0.0")


class Counts(TypedDict):
    words: int
    characters: int
    sentences: int


@mcp.tool()
def word_count(text: str) -> Counts:
    """Count words, characters, and sentences in a block of text."""
    words = text.split()
    sentences = [s for s in text.replace("!", ".").replace("?", ".").split(".") if s.strip()]
    return Counts(words=len(words), characters=len(text), sentences=len(sentences))


@mcp.tool()
def slugify(text: str) -> str:
    """Turn a title into a URL-safe slug."""
    keep = [c.lower() if c.isalnum() else "-" for c in text.strip()]
    slug = "".join(keep)
    while "--" in slug:
        slug = slug.replace("--", "-")
    return slug.strip("-")


@mcp.resource("info://server")
def server_info() -> str:
    """Static metadata a client can read without calling a tool."""
    return "text-tools v1.0.0: word_count, slugify"


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

"""End-to-end test: spawn server.py over stdio, connect a client, exercise it."""
import asyncio
from mcp import ClientSession, StdioServerParameters, stdio_client


async def main() -> None:
    params = StdioServerParameters(command="uv", args=["run", "python", "server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            tools = await session.list_tools()
            names = sorted(t.name for t in tools.tools)
            assert names == ["slugify", "word_count"], names

            r = await session.call_tool("word_count", {"text": "Hello world. How are you?"})
            data = r.structured_content
            assert data == {"words": 5, "characters": 25, "sentences": 2}, data

            r2 = await session.call_tool("slugify", {"text": "How to Build an MCP Server!"})
            assert r2.structured_content["result"] == "how-to-build-an-mcp-server", r2.structured_content

            res = await session.list_resources()
            assert any(str(x.uri) == "info://server" for x in res.resources), res.resources
            body = await session.read_resource("info://server")
            assert "text-tools" in body.contents[0].text

            print("tools:", names)
            print("word_count:", data)
            print("slugify:", r2.structured_content["result"])
    print("ALL CHECKS PASSED")


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

uv run python test_server.py

tools: ['slugify', 'word_count']
word_count: {'words': 5, 'characters': 25, 'sentences': 2}
slugify: how-to-build-an-mcp-server
ALL CHECKS PASSED

{
  "mcpServers": {
    "text-tools": {
      "command": "uv",
      "args": ["--directory", "/abs/path/to/text-tools", "run", "python", "server.py"]
    }
  }
}