agentleFS
conectlensconectlens/lenserfight/.agents/skills/mcp-manager/SKILL.md

mcp-manager

Skill18 starsChanged 6 months agoMITView on GitHub

Use when creating, registering, reviewing, or debugging MCP tools in apps/mcp-server/. Covers adding tools to any domain (lens/battle/workflow), scaffolding tool files, wiring registration, reviewing MCP PRs, and debugging auth/RPC/transport failures — even when the user doesn't say "MCP" but is working in apps/mcp-server/ or asking about adding AI tool capabilities to LenserFight.

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

MCP Manager

When to use

  • Adding a new tool (any domain or a new one)
  • Reviewing a PR that touches apps/mcp-server/
  • Debugging 401s, RPC errors, or transport failures
  • Changing OAuth flow or transport architecture

Layout

apps/mcp-server/src/
  main.ts               # entry: bootHttp | bootStdio
  types.ts              # ok() fail() paginated() zUuid
  config.ts             # getConfig() → McpServerConfig
  middleware/auth.ts    # resolveAuth() → AuthContext
  transport/http.ts     # HTTP + OAuth + session map
  transport/stdio.ts    # stdio (service-role, no auth)
  tools/
    lens/               # lens-*.ts  +  index.ts → registerLensTools()
    battle/             # battle-*.ts + index.ts → registerBattleTools()
    workflow/           # workflow-*.ts + index.ts → registerWorkflowTools()

Naming rule

Two separate conventions — keep them consistent:

ArtifactConventionExample
File stem<domain>-<action> kebablens-get-version.ts
MCP tool nameverb_noun verb-first snake_caseget_lens_version
Export functionregister<Domain><Action> PascalCaseregisterLensGetVersion
Supabase RPCfn_mcp_<domain>_<action> domain-firstfn_mcp_lens_get_version

MCP tool names are verb-first so AI agents can group by action (get_*, list_*). File stems are domain-first so tools sort together on disk.

Verb prefix in use: get_* list_* create_* update_* delete_* run_* search_* set_* archive_* fork_* submit_* retry_* summarize_* find_and_run_* validate_* extract_* add_*

Multi-word actions: first action-word becomes the verb, domain slots in second. battle-submit-run.ts → tool submit_battle_run, RPC fn_mcp_battle_submit_run

Tool template

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { SupabaseClient } from '@supabase/supabase-js';
import { ok, fail, zUuid } from '../../types.js';

export function registerLensPin(server: McpServer, sb: SupabaseClient): void {
  server.tool(
    'pin_lens',                          // verb_noun — verb first
    'Pin a lens to the caller\'s profile.',
    { lens_id: zUuid },
    async ({ lens_id }) => {
      const t0 = Date.now();
      try {
        const { data, error } = (await sb.rpc('fn_mcp_lens_pin' as never, {  // fn_mcp_domain_action
          p_lens_id: lens_id,
        })) as unknown as { data: unknown; error: { message: string } | null };
        if (error) throw new Error(error.message);
        if (!data) return fail('NOT_FOUND', `Lens ${lens_id} not found`, {}, 'pin_lens', t0);
        return ok(data, 'pin_lens', t0);
      } catch (e) {
        return fail('DB_ERROR', (e as Error).message, {}, 'pin_lens', t0);
      }
    }
  );
}

Register it

// tools/lens/index.ts — add one import + one call
import { registerLensPin } from './lens-pin.js';
export function registerLensTools(server, sb) {
  // ...existing...
  registerLensPin(server, sb);
}

main.ts already calls registerLensTools — no changes needed there.

Creation checklist

  • File: tools/<domain>/<domain>-<action>.ts
  • Tool name: verb_noun verb-first (e.g. pin_lens, submit_battle_run)
  • Export: register<Domain><Action> PascalCase words from file stem
  • RPC: fn_mcp_<domain>_<action> domain-first, mirrors file stem
  • UUID params use zUuid (not z.string().uuid())
  • const t0 = Date.now() before try
  • RPC cast: as never + explicit result type
  • if (error) throw new Error(error.message) after each RPC
  • fail('NOT_FOUND', ...) for null row; fail('DB_ERROR', ...) in catch
  • No getServiceClient() inside the handler
  • DB access via fn_mcp_* RPC only — never .schema(), .from(), or any query builder
  • Registered in tools/<domain>/index.ts
  • Docs updated: docs/en/reference/mcp-server/tools-<domain>.md

Scripts

bash scripts/new-tool.sh lens pin              # → tools/lens/lens-pin.ts, tool: pin_lens
bash scripts/new-tool.sh lens get-version      # → tools/lens/lens-get-version.ts, tool: get_lens_version
bash scripts/validate-tool.sh <file.ts>       # check conventions

Reference

  • REFERENCE.md — transport, auth, helpers, error codes, debug
  • PR checklist — full PR review checklist

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.