Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions .github/workflows/fastmcp-native.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: FastMCP native examples

on:
pull_request:
branches: [main]
paths:
- 'src/pages/docs/integrations/frameworks/fastmcp.mdx'
- 'scripts/test_fastmcp_native.py'
- 'scripts/fastmcp-page.test.mjs'
- 'src/lib/integrations.mjs'
- '.github/workflows/fastmcp-native.yml'

permissions:
contents: read

jobs:
native-contract:
runs-on: ubuntu-latest
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
include:
- python: '3.10'
fastmcp: '4.1.0'
- python: '3.13'
fastmcp: '4.1.5'
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install published packages
run: python -m pip install "fastmcp==${{ matrix.fastmcp }}" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http pytest
- name: Check native guide discovery and wording
run: node --test scripts/fastmcp-page.test.mjs
- name: Run real snippets with loopback networking only
run: |
PYTHON=$(command -v python)
sudo unshare --net bash -c 'ip link set lo up; exec "$1" -I -m pytest --noconftest -q "$2"' -- "$PYTHON" "$PWD/scripts/test_fastmcp_native.py"
36 changes: 36 additions & 0 deletions scripts/fastmcp-page.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { integrations } from '../src/lib/integrations.mjs';

const route = '/docs/integrations/frameworks/fastmcp';

test('native MCP and FastMCP routes remain distinct and discoverable', () => {
assert.ok(integrations.some(item => item.id === 'mcp-python' && item.href === '/docs/integrations/traceai/mcp-python'));
const generic = readFileSync(new URL('../src/pages/docs/integrations/traceai/mcp.mdx', import.meta.url), 'utf8');
assert.ok(generic.includes('](/docs/integrations/traceai/mcp-python)'));
assert.ok(generic.includes(`](${route})`));
});

test('native CI covers the declared floor and current published patch', () => {
const workflow = readFileSync(new URL('../.github/workflows/fastmcp-native.yml', import.meta.url), 'utf8');
assert.match(workflow, /fastmcp: '4\.1\.0'/);
assert.match(workflow, /fastmcp: '4\.1\.5'/);
});

test('Python FastMCP has its own discoverable native setup', () => {
assert.ok(integrations.some(item => item.id === 'fastmcp-python' && item.href === route));
const page = readFileSync(new URL(`../src/pages${route}.mdx`, import.meta.url), 'utf8');
assert.match(page, /fastmcp>=4\.1\.0,<4\.2/);
assert.match(page, /trace\.set_tracer_provider\(provider\)/);
assert.match(page, /project_name/);
assert.match(page, /project_type.*observe/);
assert.match(page, /X-Api-Key/);
assert.match(page, /X-Secret-Key/);
assert.match(page, /provider\.shutdown\(\)/);
assert.match(page, /mcp\.session\.id/);
assert.match(page, /\*\*Unknown\*\*/);
assert.match(page, /exception messages and stack traces/);
assert.match(page, /FI_HIDE_INPUTS.*FI_HIDE_OUTPUTS.*FI_HIDE_ERROR_DETAILS/);
assert.doesNotMatch(page, /MCPInstrumentor\(\)|class .*Exporter|class .*Processor/);
});
229 changes: 229 additions & 0 deletions scripts/test_fastmcp_native.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,229 @@
"""Execute the page's exact snippets with published FastMCP and a loopback OTLP receiver.

Install fastmcp, opentelemetry-sdk, opentelemetry-exporter-otlp-proto-http and
pytest first. Run with outbound networking denied except localhost.
"""

import gzip
import os
from pathlib import Path
import re
import signal
import socket
import subprocess
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceRequest
import pytest

PAGE = Path(__file__).resolve().parents[1] / "src/pages/docs/integrations/frameworks/fastmcp.mdx"
# -I prevents ambient Python imports; only our extracted, authored examples are added.
LOADER = "import sys,runpy; sys.path.insert(0,sys.argv[1]); runpy.run_path(sys.argv[2],run_name='__main__')"


def attrs(items):
return {item.key: getattr(item.value, item.value.WhichOneof("value")) for item in items}


@pytest.fixture
def example(tmp_path):
blocks = re.findall(r"```python\n# (\w+\.py)\n(.*?)\n```", PAGE.read_text(), re.S)
assert {name for name, _ in blocks} == {"tracing.py", "server.py", "client.py"}
for name, code in blocks:
(tmp_path / name).write_text(code)
(tmp_path / "home").mkdir()
return tmp_path


@pytest.fixture
def receiver():
received = []

class Handler(BaseHTTPRequestHandler):
def do_POST(self):
data = self.rfile.read(int(self.headers["Content-Length"]))
compressed = self.headers.get("Content-Encoding") == "gzip"
if compressed:
data = gzip.decompress(data)
payload = ExportTraceServiceRequest.FromString(data)
received.append((self.path, dict(self.headers), compressed, payload))
self.send_response(200)
self.send_header("Content-Type", "application/x-protobuf")
self.send_header("Content-Length", "0")
self.end_headers()

def log_message(self, *_args):
pass

server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
try:
yield f"http://127.0.0.1:{server.server_port}/tracer/v1/traces", received
finally:
server.shutdown()
server.server_close()
thread.join(timeout=5)


def environment(example, receiver, compression):
return {
"PATH": str(Path(sys.executable).parent) + os.pathsep + os.defpath,
"HOME": str(example / "home"),
"FI_API_KEY": "synthetic-fastmcp-api",
"FI_SECRET_KEY": "synthetic-fastmcp-secret",
"FI_PROJECT_NAME": "fastmcp-calculator",
"FASTMCP_TELEMETRY_MODE": "native",
"FASTMCP_CHECK_FOR_UPDATES": "off",
"FI_HIDE_INPUTS": "true",
"FI_HIDE_OUTPUTS": "true",
"FI_HIDE_ERROR_DETAILS": "true",
"OTEL_EXPORTER_OTLP_TRACES_ENDPOINT": receiver[0],
"OTEL_EXPORTER_OTLP_TRACES_COMPRESSION": compression,
"OTEL_BSP_SCHEDULE_DELAY": "60000",
}


def command(example, name):
return [sys.executable, "-I", "-c", LOADER, str(example), str(example / name)]


def run(example, name, env):
result = subprocess.run(command(example, name), cwd=example, env=env,
capture_output=True, text=True, timeout=45)
assert result.returncode == 0, result.stderr
return result.stdout


def exported(receiver, compression):
assert receiver[1], "no OTLP export reached the receiver"
spans = []
for path, headers, compressed, payload in receiver[1]:
headers = {key.lower(): value for key, value in headers.items()}
assert path == "/tracer/v1/traces"
assert headers["content-type"] == "application/x-protobuf"
assert headers["x-api-key"] == "synthetic-fastmcp-api"
assert headers["x-secret-key"] == "synthetic-fastmcp-secret"
assert compressed == (compression == "gzip")
for resource in payload.resource_spans:
resource_attrs = attrs(resource.resource.attributes)
assert resource_attrs["project_name"] == "fastmcp-calculator"
assert resource_attrs["project_type"] == "observe"
for scope in resource.scope_spans:
for span in scope.spans:
assert span.end_time_unix_nano >= span.start_time_unix_nano
# Export credentials belong only in HTTP headers, never span data.
assert b"synthetic-fastmcp" not in span.SerializeToString()
spans.append((scope.scope.name, span))
assert len({span.span_id for _, span in spans}) == len(spans)
return spans


def assert_tool_ancestry(spans, tool="add"):
native = [span for scope, span in spans
if scope == "fastmcp" and attrs(span.attributes).get("gen_ai.tool.name") == tool]
server = [span for span in native if span.kind == 2] # OTLP SERVER
client = [span for span in native if span.kind == 3] # OTLP CLIENT
assert len(server) == len(client) == 1, "one native execution and one logical call"
assert server[0].trace_id == client[0].trace_id
by_id = {span.span_id: span for _, span in spans}
parent = server[0]
visited = set()
while parent.span_id != client[0].span_id:
assert parent.span_id not in visited, "cycle in exported parent chain"
visited.add(parent.span_id)
parent = by_id[parent.parent_span_id]
assert attrs(server[0].attributes)["mcp.method.name"] == "tools/call"
return server[0], client[0]


@pytest.mark.parametrize("compression", ["none", "gzip"])
def test_exact_http_snippets(example, receiver, compression):
env = environment(example, receiver, compression)
with socket.socket() as reserved:
reserved.bind(("127.0.0.1", 0))
env["MCP_PORT"] = str(reserved.getsockname()[1])
process = subprocess.Popen(command(example, "server.py"), cwd=example, env=env,
stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
try:
deadline = time.monotonic() + 30
while True:
try:
with socket.create_connection(("127.0.0.1", int(env["MCP_PORT"])), timeout=0.2):
break
except OSError:
assert process.poll() is None, process.communicate()[1]
assert time.monotonic() < deadline, "server did not become ready"
threading.Event().wait(0.05)
assert run(example, "client.py", env).strip() == "5"
finally:
if process.poll() is None:
process.send_signal(signal.SIGINT)
try:
_, stderr = process.communicate(timeout=15)
except subprocess.TimeoutExpired:
process.kill()
process.communicate()
pytest.fail("server did not shut down cleanly")
assert process.returncode == 0, stderr
assert_tool_ancestry(exported(receiver, compression))


@pytest.mark.parametrize("transport", ["inprocess", "stdio"])
@pytest.mark.parametrize("compression", ["none", "gzip"])
def test_native_transport_and_privacy(example, receiver, transport, compression):
env = environment(example, receiver, compression)
# Test-only operations expose whether normal content and errors enter telemetry.
(example / "operations.py").write_text('''from server import server
@server.tool
def echo(value: str) -> str:
return value
@server.tool
def fail() -> str:
raise ValueError("synthetic-error-detail")
''')
(example / "stdio_server.py").write_text('''from tracing import provider
from operations import server
try:
server.run(transport="stdio", show_banner=False)
finally:
provider.shutdown()
''')
if transport == "inprocess":
target = "from operations import server\ntarget = server"
else:
target = f'''import os, sys
from fastmcp.client.transports import StdioTransport
target = StdioTransport(command=sys.executable, args={command(example, "stdio_server.py")[1:]!r}, env=dict(os.environ))'''
(example / "probe.py").write_text('''import asyncio
from tracing import provider
from fastmcp import Client
from fastmcp.exceptions import ToolError
''' + target + '''
async def main():
async with Client(target) as client:
assert (await client.call_tool("add", {"a": 2, "b": 3})).data == 5
assert (await client.call_tool("echo", {"value": "synthetic-normal-content"})).data == "synthetic-normal-content"
try:
await client.call_tool("fail", {})
except ToolError:
pass
else:
raise AssertionError("tool error was swallowed")
try:
asyncio.run(main())
finally:
provider.shutdown()
''')
run(example, "probe.py", env)
spans = exported(receiver, compression)
assert_tool_ancestry(spans)
assert_tool_ancestry(spans, "echo")
errors = assert_tool_ancestry(spans, "fail")
assert all(span.status.code == 2 for span in errors)
assert not any(b"synthetic-normal-content" in span.SerializeToString() for _, span in spans)
# Pin the warning: native errors are NOT sanitized by traceAI hide flags.
assert any(b"synthetic-error-detail" in span.SerializeToString() for _, span in spans)
1 change: 1 addition & 0 deletions src/lib/integrations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,7 @@ export const integrations = [
{ id: 'instructor', name: 'Instructor', href: '/docs/integrations/traceai/instructor', category: 'frameworks', summary: 'Trace structured-output requests and validation.', method: 'traceAI SDK', logo: 'instructor' },
{ id: 'promptflow', name: 'Prompt Flow', href: '/docs/integrations/traceai/promptflow', category: 'frameworks', summary: 'Trace OpenAI calls inside Prompt Flow pipelines.', method: 'OpenAI client', logo: 'promptflow', aliases: ['PromptFlow'] },
{ id: 'guardrails', name: 'Guardrails AI', href: '/docs/integrations/traceai/guardrails', category: 'frameworks', summary: 'Capture validation and guard execution spans.', method: 'traceAI SDK', logo: 'guardrails' },
{ id: 'fastmcp-python', name: 'FastMCP Python', href: '/docs/integrations/frameworks/fastmcp', category: 'frameworks', summary: 'Export native Python MCP client and server spans.', method: 'Native OTLP', logo: 'mcp' },
{ id: 'mcp-python', name: 'MCP for Python', href: '/docs/integrations/traceai/mcp-python', category: 'frameworks', summary: 'Export native MCP 2.x client requests and server tool spans.', method: 'Native OTLP', logo: 'mcp', aliases: ['Model Context Protocol Python'] },
{ id: 'mcp', name: 'Model Context Protocol', href: '/docs/integrations/traceai/mcp', category: 'frameworks', summary: 'Propagate context with TypeScript and existing Python MCP integrations.', method: 'traceAI SDK', logo: 'mcp', aliases: ['MCP'] },
{ id: 'mastra', name: 'Mastra', href: '/docs/integrations/traceai/mastra', category: 'frameworks', summary: 'Trace TypeScript agents and workflows in Mastra.', method: 'traceAI SDK', logo: 'mastra' },
Expand Down
Loading
Loading