Mellow Tapir Radio Spectrum Guide

Tapir MCP Server

此目录包含一个支持 stdio 和 streamable HTTP 传输方式的 MCP 服务。 该服务使用 src/tapir_schema/seed.json 中的数据和 src/tapir_schema/schema.sql 中的源架构文本，然后提供只读 SQLite 目录。

Python 环境

使用现有的本地虚拟环境：

cd src/tapir_mcp_server
./venv/bin/python -m pip install -r requirements.txt

构建 SQLite 数据库

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
./venv/bin/python -m mcp_server.build_db \
  --db-path data/tapir.sqlite \
  --seed-path ../tapir_schema/seed.json \
  --schema-path ../tapir_schema/schema.sql

以 stdio 模式运行

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
TAPIR_DB_PATH=data/tapir.sqlite \
TAPIR_SEED_PATH=../tapir_schema/seed.json \
TAPIR_SCHEMA_PATH=../tapir_schema/schema.sql \
./venv/bin/python -m mcp_server --transport stdio

以 HTTP 模式运行

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
TAPIR_DB_PATH=data/tapir.sqlite \
TAPIR_SEED_PATH=../tapir_schema/seed.json \
TAPIR_SCHEMA_PATH=../tapir_schema/schema.sql \
REFERENCE_LLM_MODEL=gpt-oss:20b \
OLLAMA_BASE_URL=http://127.0.0.1:11434 \
./venv/bin/python -m mcp_server \
  --transport http --host 0.0.0.0 --port 8000 --path /mcp

使用 Ollama gpt-oss:20b 在本地测试

启动 Ollama 并确保参考模型已就绪：

ollama serve

在另一个终端中：

ollama pull gpt-oss:20b
ollama run gpt-oss:20b "Summarize the purpose of this MCP server in one sentence."

使用相同的本地 Ollama 端点运行 MCP 服务：

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
TAPIR_DB_PATH=data/tapir.sqlite \
TAPIR_SEED_PATH=../tapir_schema/seed.json \
TAPIR_SCHEMA_PATH=../tapir_schema/schema.sql \
REFERENCE_LLM_MODEL=gpt-oss:20b \
OLLAMA_BASE_URL=http://127.0.0.1:11434 \
./venv/bin/python -m mcp_server --transport http --host 127.0.0.1 --port 8000 --path /mcp

连接 MCP 客户端后，使用测试提示词调用 ask_reference_model。 如果 Ollama 可访问且模型已就绪，该工具会返回响应正文 和包含模型及完成状态的元数据。

本地 MCP 会话示例（使用 Ollama）

此示例会话用于验证端到端行为：

1. 构建或刷新 SQLite 目录。
2. 启动 Ollama 并拉取 gpt-oss:20b。
3. 通过 HTTP 启动 MCP 服务。
4. 使用客户端连接并调用工具。

终端 1：启动 Ollama

ollama serve

终端 2：拉取模型并运行可选的健全性提示词

ollama pull gpt-oss:20b
ollama run gpt-oss:20b "Reply with: Ollama ready"

终端 3：启动 Tapir MCP 服务

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
./venv/bin/python -m mcp_server.build_db \
  --db-path data/tapir.sqlite \
  --seed-path ../tapir_schema/seed.json \
  --schema-path ../tapir_schema/schema.sql

TAPIR_DB_PATH=data/tapir.sqlite \
TAPIR_SEED_PATH=../tapir_schema/seed.json \
TAPIR_SCHEMA_PATH=../tapir_schema/schema.sql \
REFERENCE_LLM_MODEL=gpt-oss:20b \
OLLAMA_BASE_URL=http://127.0.0.1:11434 \
./venv/bin/python -m mcp_server --transport http --host 127.0.0.1 --port 8000 --path /mcp

终端 4：客户端请求示例

cd /Users/gsc/github/mellow-tapir
/Users/gsc/github/mellow-tapir/src/tapir_mcp_server/venv/bin/python - <<'PY'
import anyio
from mcp.client.session import ClientSession
from mcp.client.streamable_http import streamable_http_client


async def main() -> None:
    async with streamable_http_client("http://127.0.0.1:8000/mcp") as (
        read_stream,
        write_stream,
    ):
        session = ClientSession(read_stream, write_stream)
        async with session:
            await session.initialize()

            classify = await session.call_tool(
                "classify_frequency", {"frequency": "121.5"}
            )
            print("classify_frequency:")
            print(classify.content[0].text)

            llm = await session.call_tool(
                "ask_reference_model",
                {
                    "prompt": "Explain 121.5 MHz in one sentence.",
                    "temperature": 0.1,
                },
            )
            print("ask_reference_model:")
            print(llm.content[0].text)


anyio.run(main)
PY

预期结果：

• classify_frequency 返回 121.5 MHz 附近的航空紧急频道数据。
• ask_reference_model 返回来自本地 Ollama 模型 gpt-oss:20b 的补全结果。

可用工具

• classify_frequency
  • 用途：将单个频率分类到匹配频段和精确的已知频道。
  • 输入：以数字 Hz、MHz 字符串（121.5）或显式单位（121.5MHz）表示的 frequency。
  • 输出：频率元数据、频道匹配项，以及包含发射类型的频段匹配项。
• query_channels
  • 用途：列出某个频率范围内的已知频道。
  • 输入：lower_hz、upper_hz，以及可选的 limit。
  • 输出：按顺序排列的频道行，包含标签、服务和发射类型。
• search_services
  • 用途：搜索服务名称和用途名称中的文本。
  • 输入：service_query，以及可选的 limit。
  • 输出：匹配的服务／用途组合及范围摘要。
• execute_readonly_sql
  • 用途：对 SQLite 目录执行临时只读分析。
  • 输入：SQL SELECT 或 WITH 查询，以及可选的 limit。
  • 输出：列列表、行列表和行数。
  • 防护措施：拒绝写入操作。
• ask_reference_model
  • 用途：通过 Ollama 查询本地参考大模型。
  • 输入：prompt、可选的 system_prompt、可选的 temperature。
  • 输出：模型响应文本和补全元数据。
  • 默认模型：gpt-oss:20b（使用 REFERENCE_LLM_MODEL 覆盖）。

可用资源

• tapir://metadata
• tapir://sources/seed-json
• tapir://sources/schema-sql

Docker

在本地构建：

cd /Users/gsc/github/mellow-tapir
docker build -f src/tapir_mcp_server/Dockerfile -t tapir-mcp:local .

运行：

docker run --rm -p 8080:8080 \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  tapir-mcp:local

.github/workflows/tapir-mcp-server-image.yml 中的 GitHub Actions 工作流会将镜像发布到 GitHub Container Registry。

SQLite 数据沿袭与刷新

data/tapir.sqlite 中的 SQLite 数据库由两个源文件生成：

• src/tapir_schema/seed.json：可编辑的规范目录，包含频段、辐射和信道。
• src/tapir_schema/schema.sql：保留用于溯源和一致性检查的源 PostgreSQL 架构。

生成工作由 mcp_server.build_db 负责，它会：

• 创建 SQLite 表（band、band_emission、channel、dataset_metadata），
• 从 seed.json 重新加载记录，
• 存储源溯源元数据（包括源路径和架构 SQL 文本），
• 生成可供 MCP 服务以只读模式使用的就绪文件。

今后更新数据集时：

1. 编辑 src/tapir_schema/seed.json。
2. 如果源架构的意图发生变化，可选地更新 src/tapir_schema/schema.sql。
3. 重新构建 SQLite：

cd /Users/gsc/github/mellow-tapir/src/tapir_mcp_server
./venv/bin/python -m mcp_server.build_db \
  --db-path data/tapir.sqlite \
  --seed-path ../tapir_schema/seed.json \
  --schema-path ../tapir_schema/schema.sql

4. 重启 MCP 服务，使其使用刷新的 SQLite 文件。

容器映像构建也会在 docker build 期间执行相同的构建步骤， 因此映像内容会与最新提交的 seed.json 和 schema.sql 保持一致。