agentmods.dev

ai-mcp-server: Instructions file for Codex

AGENTS.md

ai-mcp-server AGENTS.md is an instructions file for Codex, OpenCode from brianMacao/ai-mcp-server. It costs 3,243 tokens per session, scanned A, original, MIT.

Repository-specific instructions for ai-mcp-server, a local tool collection that lets agents query and call different AI models through one system.

In plain words
What is it for?
Use them when changing ai-mcp-server so edits follow its project boundaries, backend design, storage rules, and delivery conventions.
Why use it?
They tell coding assistants which parts of the repository are in scope and how its command-line tool, web interface, MCP server, application logic, and local database are expected to work together.

Instructions file for CodexOpenCode

Written for Codex and OpenCode: the file is AGENTS.md. Also seen: built for cline.

This is brianMacao/ai-mcp-server's own configuration. It tells Codex and OpenCode how to work on ai-mcp-server itself, so it is not a mod to install elsewhere. Copy it as a starting point and replace the rules that are about this project. Everything ai-mcp-server configures →

not rated 0repo 4mo ago A scan 3,243 tokens original MIT
View source ↗ brianMacao/ai-mcp-server
Reuse

Borrowing it

Nothing to install: this file belongs to brianMacao/ai-mcp-server. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.

Copy the file
curl -O https://raw.githubusercontent.com/brianMacao/ai-mcp-server/main/AGENTS.md
Clone the repo
git clone --depth 1 https://github.com/brianMacao/ai-mcp-server

Made for: Codex, OpenCode.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for ai-mcp-server AGENTS.md

README.md
[![agentmods](https://agentmods.dev/badge/instructions/brianmacao/ai-mcp-server/agents-md/github.svg)](https://agentmods.dev/instructions/brianmacao/ai-mcp-server/agents-md)
Your own site
<a href="https://agentmods.dev/instructions/brianmacao/ai-mcp-server/agents-md"><img src="https://agentmods.dev/badge/instructions/brianmacao/ai-mcp-server/agents-md/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for ai-mcp-server AGENTS.md

Your own site · 80×15
<a href="https://agentmods.dev/instructions/brianmacao/ai-mcp-server/agents-md"><img src="https://agentmods.dev/badge/instructions/brianmacao/ai-mcp-server/agents-md.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 3,243 This file is loaded in full into every session.
When invoked 3,243 The same file — it is already loaded in full.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.03243 $0.03243
Opus 5.5 $0.01297 $0.01297
Sonnet 5.5 $0.00649 $0.00649
Haiku 4.5 $0.00324 $0.00324

Measured 2mo ago against content hash c8294838a1b7, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

ai-mcp-server AGENTS.md scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2mo ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

AGENTS.md · 167 lines

How it starts

The opening of the file, as written. The whole thing — 167 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Coding Assistant 協作指引

項目範圍

本倉庫只維護 ai-mcp-server：一個本地工具集合，包含三個獨立進程入口（MCP server stdio、CLI、 Web UI），把多個 (api_key, base_url) 收編成統一的能力池，讓 Agent 透過 MCP 查詢與調用各種模型 （chat / vision / reasoning / embedding / image_gen / tts / stt / rerank）。

  • Python 包：src/ai_mcp_server/
  • CLI 入口：ai-mcp（由 pyproject.toml 定義 entry point；含 endpoint / model / meta / worker / ui 子命令）
  • MCP server 入口：ai-mcp-server（stdio 模式，被 Agent 客戶端拉起；啟動時內含背景 worker task）
  • Web UI 入口：ai-mcp ui（FastAPI + Jinja2 + uvicorn；綁定 127.0.0.1，無認證）
  • 本地數據：~/.ai-mcp-server/db.sqlite3（WAL 模式），api_key 以 Fernet 加密儲存

新增工作默認限制在 src/ai_mcp_server/、tests/、assets/、docs/。不要新增無關 workspace 或包；舊文檔中的舊結構引用只作背景。

後端架構原則：解讀 X

本項目採「邏輯單一後端」：三個進程入口（MCP server / CLI / Web UI）不共享進程，但共享 同一份 application/* 業務邏輯與同一個 SQLite。

  • 每個入口進程都 import ai_mcp_server.application.* 直接 in-process 調業務函數。
  • 不走 subprocess 反代、不走 HTTP 反代到「那個唯一後端」。
  • 真相在 SQLite（WAL 模式 + busy_timeout=5000 支援多進程並發讀寫）。
  • 探活異步化：UI / CLI / MCP 任一入口都可以 enqueue probe_jobs；worker 由 MCP server 進程內背景 asyncio task 承擔，CLI endpoint probe 也可同步消化 queue 至清空。

設計哲學

  • 橋樑優先，不做攔截：MCP server 對上游 API 盡量原樣透傳；除了協議格式轉換與能力路由， 不對 messages、tool_calls、parameters 做業務語義改寫。
  • KISS 版分層：Python 單體；分層用來讓代碼有清晰落點，不是引入厚重架構儀式。 先問落點：它代表 MCP tool 入口、用戶動作編排、能力解析、provider 防腐、儲存基礎能力， 還是純工具函數。
  • 靜態優先、探活兜底：能力標籤先信靜態映射與第三方 metadata；探活只在用戶手動觸發時跑， 不在 server 啟動或 tool 調用路徑上偷偷打 API。
  • 可追溯與可預測：不要隱藏錯誤或風險；上游 API 的錯誤原樣冒泡到 Agent，附帶足夠 context 讓 Agent 能決策重試或換模型。失敗可定位優先於表面成功率。
  • 簡單但不混亂：能用簡單函數清楚表達的邏輯就保持簡單；一旦涉及跨 provider、跨能力路由 或多來源融合，必須回到清晰分層和可測邊界。

名詞與交付面

  • MCP server：本倉庫主交付物，stdio 模式長駐進程，由 Agent 客戶端（Claude Desktop、 Cursor、Cline 等）按需拉起。
  • MCP tool：暴露給 Agent 的 6 個 tool —— usage_guide / list_models / invoke_model / model_performance / refresh_endpoint / add_models。
  • endpoint：用戶登記的一組 (name, base_url, api_key, provider_type)，代表一個上游 API。
  • model：endpoint 下發現的單一模型，附帶 capabilities 標籤（vision / tool_call / context_length 等）。
  • capability：模型能力標籤，融合來源有四：用戶覆寫 > 探活結果 > 第三方 metadata (LiteLLM)

    內建靜態映射表。

  • probe：能力探活，發最小 payload（內容統一用「1」）驗證模型在某能力上是否真實可用。
  • provider adapter：協議防腐層，當前只有 OpenAICompatAdapter，Anthropic 預留接口。
  • CLI：ai-mcp 命令，用於登記 endpoint、查詢模型、手動覆寫能力、觸發探活。

Read the full file on GitHub · 167 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2mo ago First seen · 167 lines · 3,243 tokens per session scan A c8294838a1b7

Subscribe to this mod's changes

ai-mcp-server AGENTS.md is an instructions file published in the GitHub repository brianMacao/ai-mcp-server (0 stars, last pushed 4mo ago), licensed MIT. It adds 3,243 tokens to every session, about $0.0130 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-01.

Related

ai-mcp-server AGENTS.md compared with instructions from other repositories

ai-mcp-server AGENTS.md next to 6 instructions from other repositories
ModTypeStarsLast pushLicenceScanTokensWorks with
ai-mcp-server AGENTS.mdbrianMacao/ai-mcp-serverInstructions file04mo agoMITA3,243Codex, OpenCode
vscode buildNext.instructions.mdmicrosoft/vscodeInstructions file195kyesterdayMITA9,719GitHub Copilot
next.js AGENTS.mdvercel/next.jsInstructions file143kyesterdayMITA7,461Codex, OpenCode
langchain AGENTS.mdlangchain-ai/langchainInstructions file149kyesterdayMITA4,680Codex, OpenCode
vscode oss-third-party-notices.instructions.mdmicrosoft/vscodeInstructions file195kyesterdayMITA5,516GitHub Copilot
vscode copilot-instructions.mdmicrosoft/vscodeInstructions file195kyesterdayMITA3,093GitHub Copilot
deepseek-harness AGENTS.mddeepseek-ai/deepseek-harnessInstructions file274k2d agoMITA4,313Codex, OpenCode