Skip to content

MCP Server Reference

BioMCP exposes one execution tool (shell) and a curated resource catalog for agent guidance. This page documents the stable MCP contract and executes lightweight checks against the source tree.

Capability Advertisement

The server must advertise both tools and resources.

Capability Required
tools enabled
resources enabled 
from pathlib import Path

repo_root = Path.cwd()
shell = (repo_root / "src/mcp/shell.rs").read_text()
assert "enable_tools()" in shell
assert "enable_resources()" in shell

Resource Catalog

BioMCP publishes a help resource plus one markdown resource per registered skill use-case.

URI Name
biomcp://help BioMCP Overview
biomcp://skill/<slug> Pattern: <title> 
import re
from pathlib import Path

repo_root = Path.cwd()
shell = (repo_root / "src/mcp/shell.rs").read_text()
assert "RESOURCE_HELP_URI" in shell
assert 'uri: RESOURCE_HELP_URI.to_string()' in shell
assert 'name: "BioMCP Overview".to_string()' in shell
assert "list_use_case_refs()" in shell
assert 'format!("biomcp://skill/{}", skill.slug)' in shell
assert 'name = if title.to_ascii_lowercase().starts_with("pattern:")' in shell
assert len(set(re.findall(r"biomcp://[a-z0-9/-]+", shell))) >= 2

Resource Read Mapping

  • biomcp://help maps to show_overview().
  • Skill URIs map to show_use_case(<slug>).
  • All successful reads return text/markdown.
from pathlib import Path

repo_root = Path.cwd()
shell = (repo_root / "src/mcp/shell.rs").read_text()
assert "show_overview()" in shell
assert 'if let Some(slug) = uri.strip_prefix("biomcp://skill/")' in shell
assert "show_use_case(slug)" in shell
assert 'mime_type: Some("text/markdown".to_string())' in shell

Unknown URI Behavior

Unknown resource URIs must return an MCP resource-not-found error and include a helpful message.

from pathlib import Path

repo_root = Path.cwd()
shell = (repo_root / "src/mcp/shell.rs").read_text()
assert "resource_not_found" in shell
assert "Unknown resource:" in shell

Companion Runtime Tests

Protocol-level checks are implemented in Python integration tests:

  • tests/conftest.py
  • tests/test_mcp_contract.py

These tests run a real biomcp serve session over stdio and validate:

  • initialize handshake,
  • tools inventory,
  • resource inventory,
  • resource reads,
  • invalid URI error semantics.
from pathlib import Path

repo_root = Path.cwd()
assert (repo_root / "tests/conftest.py").exists()
assert (repo_root / "tests/test_mcp_contract.py").exists()