Merge pull request #24 from jlowin/readme

README.md

@@ -7,11 +7,11 @@
 [![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
 [![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
 
-A fast, Pythonic way to build Model Context Protocol servers
+A fast, Pythonic way to build [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers
 
 </div>
 
-FastMCP makes building [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
+FastMCP makes building MCP servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
 
 ```python
 from fastmcp import FastMCP
@@ -26,15 +26,17 @@ def add(a: int, b: int) -> int:
 
 That's it! FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic - in most cases, decorating a function is all you need.
 
-🚨 🚧 🏗️ *FastMCP is under active development, as is the MCP specification itself. Core features are working but some advanced capabilities are still in progress.* 
 
-Key features:
+### Key features:
 * **Fast**: High-level interface means less code and faster development
 * **Simple**: Build MCP servers with minimal boilerplate
 * **Pythonic**: Feels natural to Python developers
 * **Complete***: FastMCP aims to provide a full implementation of the core MCP specification
 
-(\*emphasis on *aims* during construction)
+(\*emphasis on *aims*)
+
+🚨 🚧 🏗️ *FastMCP is under active development, as is the MCP specification itself. Core features are working but some advanced capabilities are still in progress.* 
+
 
 <!-- omit in toc -->
 ## Table of Contents
@@ -107,19 +109,21 @@ fastmcp install server.py
 fastmcp dev server.py
 ```
 
-![MCP Inspector](docs/images/mcp-inspector.png)
+![MCP Inspector](/docs/assets/demo-inspector.png)
 
 ## What is MCP?
 
 The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
 
-- Expose data through **Resources** (like GET endpoints)
-- Provide functionality through **Tools** (like POST endpoints)
+- Expose data through **Resources** (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
+- Provide functionality through **Tools** (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
 - Define interaction patterns through **Prompts** (reusable templates for LLM interactions)
+- And more!
+
+There is a low-level [Python SDK](https://github.com/modelcontextprotocol/python-sdk) available for implementing the protocol directly, but FastMCP aims to make that easier by providing a high-level, Pythonic interface.
 
 ## Core Concepts
 
-*Note: All code examples below assume you've created a FastMCP server instance called `mcp`.*
 
 ### Server
 
@@ -134,6 +138,7 @@ mcp = FastMCP("My App")
 # Configure host/port for HTTP transport (optional)
 mcp = FastMCP("My App", host="localhost", port=8000)
 ```
+*Note: All of the following code examples assume you've created a FastMCP server instance called `mcp`, as shown above.*
 
 ### Resources
 
@@ -376,4 +381,4 @@ Schema:
 {get_schema()}
 
 What insights can you provide about the structure and relationships?"""
-```
+```