fastmcp 0.3.5__tar.gz → 0.4.1__tar.gz

{fastmcp-0.3.5 → fastmcp-0.4.1}/.github/ai-labeler.yml

@@ -1,6 +1,6 @@
 instructions: |
   Apply the minimal set of labels that accurately characterize the issue/PR:
-  - Use at most 1-2 labels unless there's a compelling reason for more
+  - Use at most 1-2 labels unless there's a compelling reason for more. It's ok to use no labels.
   - Prefer specific labels (bug, feature) over generic ones (question, help wanted)
   - For PRs that fix bugs, use 'bug' not 'enhancement'
   - Never combine: bug + enhancement, feature + enhancement. For these labels, only choose the most relevant one.
@@ -12,9 +12,8 @@ labels:
     instructions: |
       Apply when describing or fixing unexpected behavior:
       - Issues: Clear error messages or unexpected outcomes
-      - PRs: Fixes for broken functionality
-      Don't apply enhancement/feature for bug fixes unless they add significant new functionality
-      beyond fixing the bug
+      - PRs: Standalone fixes for broken functionality or closing bug reports.
+      Don't apply bug unless the issue or PR is predominantly about a specific bug.
 
   - documentation:
     description: "Improvements or additions to documentation"

fastmcp-0.3.5/.github/workflows/lint.yml → fastmcp-0.4.1/.github/workflows/run-static.yml

@@ -28,3 +28,9 @@ jobs:
           python-version: "3.12"
       - name: Run pre-commit
         uses: pre-commit/action@v3.0.1
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[tests]"
+      - name: Run pyright
+        run: pyright src tests

{fastmcp-0.3.5 → fastmcp-0.4.1}/.gitignore

@@ -16,4 +16,4 @@ src/fastmcp/_version.py
 
 # editors
 .cursorrules
-.vscode/
+.vscode/

fastmcp-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jeremiah Lowin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{fastmcp-0.3.5 → fastmcp-0.4.1}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.5
+Version: 0.4.1
 Summary: A more ergonomic interface for MCP servers
 Author: Jeremiah Lowin
-License: Apache-2.0
+License: MIT
 Requires-Python: >=3.10
 Requires-Dist: httpx>=0.26.0
 Requires-Dist: mcp<2.0.0,>=1.0.0
@@ -16,13 +16,17 @@ Requires-Dist: copychat>=0.5.2; extra == 'dev'
 Requires-Dist: ipython>=8.12.3; extra == 'dev'
 Requires-Dist: pdbpp>=0.10.3; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pyright>=1.1.389; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
+Requires-Dist: pytest-flakefinder; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
 Requires-Dist: pytest>=8.3.3; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Provides-Extra: tests
 Requires-Dist: pre-commit; extra == 'tests'
+Requires-Dist: pyright>=1.1.389; extra == 'tests'
 Requires-Dist: pytest-asyncio>=0.23.5; extra == 'tests'
+Requires-Dist: pytest-flakefinder; extra == 'tests'
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'tests'
 Requires-Dist: pytest>=8.3.3; extra == 'tests'
 Requires-Dist: ruff; extra == 'tests'

fastmcp-0.4.1/examples/memory.py

@@ -0,0 +1,346 @@
+# /// script
+# dependencies = ["pydantic-ai-slim[openai]", "asyncpg", "numpy", "pgvector", "fastmcp"]
+# ///
+
+# uv pip install 'pydantic-ai-slim[openai]' asyncpg numpy pgvector fastmcp
+
+"""
+Recursive memory system inspired by the human brain's clustering of memories.
+Uses OpenAI's 'text-embedding-3-small' model and pgvector for efficient similarity search.
+"""
+
+import asyncio
+import math
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Annotated, Self
+
+import asyncpg
+import numpy as np
+from openai import AsyncOpenAI
+from pgvector.asyncpg import register_vector  # Import register_vector
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+
+from fastmcp import FastMCP
+
+MAX_DEPTH = 5
+SIMILARITY_THRESHOLD = 0.7
+DECAY_FACTOR = 0.99
+REINFORCEMENT_FACTOR = 1.1
+
+DEFAULT_LLM_MODEL = "openai:gpt-4o"
+DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small"
+
+mcp = FastMCP(
+    "memory",
+    dependencies=[
+        "pydantic-ai-slim[openai]",
+        "asyncpg",
+        "numpy",
+        "pgvector",
+    ],
+)
+
+DB_DSN = "postgresql://postgres:postgres@localhost:54320/memory_db"
+# reset memory with rm ~/.fastmcp/{USER}/memory/*
+PROFILE_DIR = (
+    Path.home() / ".fastmcp" / os.environ.get("USER", "anon") / "memory"
+).resolve()
+PROFILE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    a_array = np.array(a, dtype=np.float64)
+    b_array = np.array(b, dtype=np.float64)
+    return np.dot(a_array, b_array) / (
+        np.linalg.norm(a_array) * np.linalg.norm(b_array)
+    )
+
+
+async def do_ai[T](
+    user_prompt: str,
+    system_prompt: str,
+    result_type: type[T] | Annotated,
+    deps=None,
+) -> T:
+    agent = Agent(
+        DEFAULT_LLM_MODEL,
+        system_prompt=system_prompt,
+        result_type=result_type,
+    )
+    result = await agent.run(user_prompt, deps=deps)
+    return result.data
+
+
+@dataclass
+class Deps:
+    openai: AsyncOpenAI
+    pool: asyncpg.Pool
+
+
+async def get_db_pool() -> asyncpg.Pool:
+    async def init(conn):
+        await conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+        await register_vector(conn)
+
+    pool = await asyncpg.create_pool(DB_DSN, init=init)
+    return pool
+
+
+class MemoryNode(BaseModel):
+    id: int | None = None
+    content: str
+    summary: str = ""
+    importance: float = 1.0
+    access_count: int = 0
+    timestamp: float = Field(
+        default_factory=lambda: datetime.now(timezone.utc).timestamp()
+    )
+    embedding: list[float]
+
+    @classmethod
+    async def from_content(cls, content: str, deps: Deps):
+        embedding = await get_embedding(content, deps)
+        return cls(content=content, embedding=embedding)
+
+    async def save(self, deps: Deps):
+        async with deps.pool.acquire() as conn:
+            if self.id is None:
+                result = await conn.fetchrow(
+                    """
+                    INSERT INTO memories (content, summary, importance, access_count, timestamp, embedding)
+                    VALUES ($1, $2, $3, $4, $5, $6)
+                    RETURNING id
+                    """,
+                    self.content,
+                    self.summary,
+                    self.importance,
+                    self.access_count,
+                    self.timestamp,
+                    self.embedding,
+                )
+                self.id = result["id"]
+            else:
+                await conn.execute(
+                    """
+                    UPDATE memories
+                    SET content = $1, summary = $2, importance = $3,
+                        access_count = $4, timestamp = $5, embedding = $6
+                    WHERE id = $7
+                    """,
+                    self.content,
+                    self.summary,
+                    self.importance,
+                    self.access_count,
+                    self.timestamp,
+                    self.embedding,
+                    self.id,
+                )
+
+    async def merge_with(self, other: Self, deps: Deps):
+        self.content = await do_ai(
+            f"{self.content}\n\n{other.content}",
+            "Combine the following two texts into a single, coherent text.",
+            str,
+            deps,
+        )
+        self.importance += other.importance
+        self.access_count += other.access_count
+        self.embedding = [(a + b) / 2 for a, b in zip(self.embedding, other.embedding)]
+        self.summary = await do_ai(
+            self.content, "Summarize the following text concisely.", str, deps
+        )
+        await self.save(deps)
+        # Delete the merged node from the database
+        if other.id is not None:
+            await delete_memory(other.id, deps)
+
+    def get_effective_importance(self):
+        return self.importance * (1 + math.log(self.access_count + 1))
+
+
+async def get_embedding(text: str, deps: Deps) -> list[float]:
+    embedding_response = await deps.openai.embeddings.create(
+        input=text,
+        model=DEFAULT_EMBEDDING_MODEL,
+    )
+    return embedding_response.data[0].embedding
+
+
+async def delete_memory(memory_id: int, deps: Deps):
+    async with deps.pool.acquire() as conn:
+        await conn.execute("DELETE FROM memories WHERE id = $1", memory_id)
+
+
+async def add_memory(content: str, deps: Deps):
+    new_memory = await MemoryNode.from_content(content, deps)
+    await new_memory.save(deps)
+
+    similar_memories = await find_similar_memories(new_memory.embedding, deps)
+    for memory in similar_memories:
+        if memory.id != new_memory.id:
+            await new_memory.merge_with(memory, deps)
+
+    await update_importance(new_memory.embedding, deps)
+
+    await prune_memories(deps)
+
+    return f"Remembered: {content}"
+
+
+async def find_similar_memories(embedding: list[float], deps: Deps) -> list[MemoryNode]:
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT id, content, summary, importance, access_count, timestamp, embedding
+            FROM memories
+            ORDER BY embedding <-> $1
+            LIMIT 5
+            """,
+            embedding,
+        )
+    memories = [
+        MemoryNode(
+            id=row["id"],
+            content=row["content"],
+            summary=row["summary"],
+            importance=row["importance"],
+            access_count=row["access_count"],
+            timestamp=row["timestamp"],
+            embedding=row["embedding"],
+        )
+        for row in rows
+    ]
+    return memories
+
+
+async def update_importance(user_embedding: list[float], deps: Deps):
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            "SELECT id, importance, access_count, embedding FROM memories"
+        )
+        for row in rows:
+            memory_embedding = row["embedding"]
+            similarity = cosine_similarity(user_embedding, memory_embedding)
+            if similarity > SIMILARITY_THRESHOLD:
+                new_importance = row["importance"] * REINFORCEMENT_FACTOR
+                new_access_count = row["access_count"] + 1
+            else:
+                new_importance = row["importance"] * DECAY_FACTOR
+                new_access_count = row["access_count"]
+            await conn.execute(
+                """
+                UPDATE memories
+                SET importance = $1, access_count = $2
+                WHERE id = $3
+                """,
+                new_importance,
+                new_access_count,
+                row["id"],
+            )
+
+
+async def prune_memories(deps: Deps):
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT id, importance, access_count
+            FROM memories
+            ORDER BY importance DESC
+            OFFSET $1
+            """,
+            MAX_DEPTH,
+        )
+        for row in rows:
+            await conn.execute("DELETE FROM memories WHERE id = $1", row["id"])
+
+
+async def display_memory_tree(deps: Deps) -> str:
+    async with deps.pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT content, summary, importance, access_count
+            FROM memories
+            ORDER BY importance DESC
+            LIMIT $1
+            """,
+            MAX_DEPTH,
+        )
+    result = ""
+    for row in rows:
+        effective_importance = row["importance"] * (
+            1 + math.log(row["access_count"] + 1)
+        )
+        summary = row["summary"] or row["content"]
+        result += f"- {summary} (Importance: {effective_importance:.2f})\n"
+    return result
+
+
+@mcp.tool()
+async def remember(
+    contents: list[str] = Field(
+        description="List of observations or memories to store"
+    ),
+):
+    deps = Deps(openai=AsyncOpenAI(), pool=await get_db_pool())
+    try:
+        return "\n".join(
+            await asyncio.gather(*[add_memory(content, deps) for content in contents])
+        )
+    finally:
+        await deps.pool.close()
+
+
+@mcp.tool()
+async def read_profile() -> str:
+    deps = Deps(openai=AsyncOpenAI(), pool=await get_db_pool())
+    profile = await display_memory_tree(deps)
+    await deps.pool.close()
+    return profile
+
+
+async def initialize_database():
+    pool = await asyncpg.create_pool(
+        "postgresql://postgres:postgres@localhost:54320/postgres"
+    )
+    try:
+        async with pool.acquire() as conn:
+            await conn.execute("""
+                SELECT pg_terminate_backend(pg_stat_activity.pid)
+                FROM pg_stat_activity
+                WHERE pg_stat_activity.datname = 'memory_db'
+                AND pid <> pg_backend_pid();
+            """)
+            await conn.execute("DROP DATABASE IF EXISTS memory_db;")
+            await conn.execute("CREATE DATABASE memory_db;")
+    finally:
+        await pool.close()
+
+    pool = await asyncpg.create_pool(DB_DSN)
+    try:
+        async with pool.acquire() as conn:
+            await conn.execute("CREATE EXTENSION IF NOT EXISTS vector;")
+
+            await register_vector(conn)
+
+            await conn.execute("""
+                CREATE TABLE IF NOT EXISTS memories (
+                    id SERIAL PRIMARY KEY,
+                    content TEXT NOT NULL,
+                    summary TEXT,
+                    importance REAL NOT NULL,
+                    access_count INT NOT NULL,
+                    timestamp DOUBLE PRECISION NOT NULL,
+                    embedding vector(1536) NOT NULL
+                );
+                CREATE INDEX IF NOT EXISTS idx_memories_embedding ON memories USING hnsw (embedding vector_l2_ops);
+            """)
+    finally:
+        await pool.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(initialize_database())

{fastmcp-0.3.5 → fastmcp-0.4.1}/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
 ]
 requires-python = ">=3.10"
 readme = "README.md"
-license = { text = "Apache-2.0" }
+license = { text = "MIT" }
 
 [project.scripts]
 fastmcp = "fastmcp.cli:app"
@@ -25,8 +25,10 @@ build-backend = "hatchling.build"
 [project.optional-dependencies]
 tests = [
     "pre-commit",
+    "pyright>=1.1.389",
     "pytest>=8.3.3",
     "pytest-asyncio>=0.23.5",
+    "pytest-flakefinder",
     "pytest-xdist>=3.6.1",
     "ruff",
 ]
@@ -38,3 +40,15 @@ asyncio_default_fixture_loop_scope = "session"
 
 [tool.hatch.version]
 source = "vcs"
+
+[tool.pyright]
+include = ["src", "tests"]
+exclude = ["**/node_modules", "**/__pycache__", ".venv", ".git", "dist"]
+pythonVersion = "3.10"
+pythonPlatform = "Darwin"
+typeCheckingMode = "basic"
+reportMissingImports = true
+reportMissingTypeStubs = false
+useLibraryCodeForTypes = true
+venvPath = "."
+venv = ".venv"

{fastmcp-0.3.5 → fastmcp-0.4.1}/src/fastmcp/cli/cli.py

@@ -2,14 +2,15 @@
 
 import importlib.metadata
 import importlib.util
+import os
 import subprocess
 import sys
 from pathlib import Path
-from typing import Optional, Tuple, Dict
+from typing import Dict, Optional, Tuple
 
+import dotenv
 import typer
 from typing_extensions import Annotated
-import dotenv
 
 from fastmcp.cli import claude
 from fastmcp.utilities.logging import get_logger
@@ -242,6 +243,7 @@ def dev(
             [npx_cmd, "@modelcontextprotocol/inspector"] + uv_cmd,
             check=True,
             shell=shell,
+            env=dict(os.environ.items()),  # Convert to list of tuples for env update
         )
         sys.exit(process.returncode)
     except subprocess.CalledProcessError as e:
@@ -423,7 +425,11 @@ def install(
         # Load from .env file if specified
         if env_file:
             try:
-                env_dict.update(dotenv.dotenv_values(env_file))
+                env_dict |= {
+                    k: v
+                    for k, v in dotenv.dotenv_values(env_file).items()
+                    if v is not None
+                }
             except Exception as e:
                 logger.error(f"Failed to load .env file: {e}")
                 sys.exit(1)

{fastmcp-0.3.5 → fastmcp-0.4.1}/src/fastmcp/prompts/base.py

@@ -1,43 +1,52 @@
 """Base classes for FastMCP prompts."""
 
 import json
-from typing import Any, Callable, Dict, Literal, Optional, Sequence, Union
+from typing import Any, Callable, Dict, Literal, Optional, Sequence, Awaitable
 import inspect
 
-from pydantic import BaseModel, Field, TypeAdapter, field_validator, validate_call
+from pydantic import BaseModel, Field, TypeAdapter, validate_call
 from mcp.types import TextContent, ImageContent, EmbeddedResource
 import pydantic_core
 
+CONTENT_TYPES = TextContent | ImageContent | EmbeddedResource
+
 
 class Message(BaseModel):
     """Base class for all prompt messages."""
 
     role: Literal["user", "assistant"]
-    content: Union[TextContent, ImageContent, EmbeddedResource]
+    content: CONTENT_TYPES
 
-    def __init__(self, content, **kwargs):
+    def __init__(self, content: str | CONTENT_TYPES, **kwargs):
+        if isinstance(content, str):
+            content = TextContent(type="text", text=content)
         super().__init__(content=content, **kwargs)
 
-    @field_validator("content", mode="before")
-    def validate_content(cls, v):
-        if isinstance(v, str):
-            return TextContent(type="text", text=v)
-        return v
-
 
 class UserMessage(Message):
     """A message from the user."""
 
     role: Literal["user"] = "user"
 
+    def __init__(self, content: str | CONTENT_TYPES, **kwargs):
+        super().__init__(content=content, **kwargs)
+
 
 class AssistantMessage(Message):
     """A message from the assistant."""
 
     role: Literal["assistant"] = "assistant"
 
+    def __init__(self, content: str | CONTENT_TYPES, **kwargs):
+        super().__init__(content=content, **kwargs)
+
+
+message_validator = TypeAdapter(UserMessage | AssistantMessage)
 
-message_validator = TypeAdapter(Union[UserMessage, AssistantMessage])
+SyncPromptResult = (
+    str | Message | dict[str, Any] | Sequence[str | Message | dict[str, Any]]
+)
+PromptResult = SyncPromptResult | Awaitable[SyncPromptResult]
 
 
 class PromptArgument(BaseModel):
@@ -67,11 +76,18 @@ class Prompt(BaseModel):
     @classmethod
     def from_function(
         cls,
-        fn: Callable[..., Sequence[Message]],
+        fn: Callable[..., PromptResult],
         name: Optional[str] = None,
         description: Optional[str] = None,
     ) -> "Prompt":
-        """Create a Prompt from a function."""
+        """Create a Prompt from a function.
+
+        The function can return:
+        - A string (converted to a message)
+        - A Message object
+        - A dict (converted to a message)
+        - A sequence of any of the above
+        """
         func_name = name or fn.__name__
 
         if func_name == "<lambda>":

{fastmcp-0.3.5 → fastmcp-0.4.1}/src/fastmcp/resources/base.py

@@ -1,14 +1,14 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Union
+from typing import Union, Annotated
 
 from pydantic import (
     AnyUrl,
     BaseModel,
     ConfigDict,
     Field,
-    FileUrl,
+    UrlConstraints,
     ValidationInfo,
     field_validator,
 )
@@ -19,8 +19,9 @@ class Resource(BaseModel, abc.ABC):
 
     model_config = ConfigDict(validate_default=True)
 
-    # uri: Annotated[AnyUrl, BeforeValidator(maybe_cast_str_to_any_url)] = Field(
-    uri: AnyUrl = Field(default=..., description="URI of the resource")
+    uri: Annotated[AnyUrl, UrlConstraints(host_required=False)] = Field(
+        default=..., description="URI of the resource"
+    )
     name: str | None = Field(description="Name of the resource", default=None)
     description: str | None = Field(
         description="Description of the resource", default=None
@@ -31,15 +32,6 @@ class Resource(BaseModel, abc.ABC):
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
 
-    @field_validator("uri", mode="before")
-    def validate_uri(cls, uri: AnyUrl | str) -> AnyUrl:
-        if isinstance(uri, str):
-            # AnyUrl doesn't support triple-slashes, but files do ("file:///absolute/path")
-            if uri.startswith("file://"):
-                return FileUrl(uri)
-            return AnyUrl(uri)
-        return uri
-
     @field_validator("name", mode="before")
     @classmethod
     def set_default_name(cls, name: str | None, info: ValidationInfo) -> str:

{fastmcp-0.3.5 → fastmcp-0.4.1}/src/fastmcp/resources/templates.py

@@ -70,7 +70,7 @@ class ResourceTemplate(BaseModel):
                 result = await result
 
             return FunctionResource(
-                uri=uri,
+                uri=uri,  # type: ignore
                 name=self.name,
                 description=self.description,
                 mime_type=self.mime_type,

{fastmcp-0.3.5 → fastmcp-0.4.1}/src/fastmcp/resources/types.py

@@ -8,7 +8,7 @@ from typing import Any, Callable, Union
 import httpx
 import pydantic.json
 import pydantic_core
-from pydantic import Field
+from pydantic import Field, ValidationInfo
 
 from fastmcp.resources.base import Resource
 
@@ -91,6 +91,15 @@ class FileResource(Resource):
             raise ValueError("Path must be absolute")
         return path
 
+    @pydantic.field_validator("is_binary")
+    @classmethod
+    def set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool:
+        """Set is_binary based on mime_type if not explicitly set."""
+        if is_binary:
+            return True
+        mime_type = info.data.get("mime_type", "text/plain")
+        return not mime_type.startswith("text/")
+
     async def read(self) -> Union[str, bytes]:
         """Read the file content."""
         try: