diff --git a/docs/DEBUGGING-CHECKLIST.md b/docs/DEBUGGING-CHECKLIST.md index a47c511..43ea553 100644 --- a/docs/DEBUGGING-CHECKLIST.md +++ b/docs/DEBUGGING-CHECKLIST.md @@ -2,7 +2,7 @@ **Purpose:** Systematic approach to diagnose and fix plugin loading issues. -Last Updated: 2026-01-28 +Last Updated: 2026-02-08 --- @@ -95,9 +95,9 @@ Manually test if the MCP server can start: ```bash RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace -# Test Gitea MCP +# Test Gitea MCP (uses gitea-mcp package from registry) cd $RUNTIME/mcp-servers/gitea -PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')" +.venv/bin/python -c "from gitea_mcp.server import main; print('OK')" # Test NetBox MCP cd $RUNTIME/mcp-servers/netbox diff --git a/plugins/debug-mcp/agents/mcp-debugger.md b/plugins/debug-mcp/agents/mcp-debugger.md index 2e81f6b..5c078cf 100644 --- a/plugins/debug-mcp/agents/mcp-debugger.md +++ b/plugins/debug-mcp/agents/mcp-debugger.md @@ -43,6 +43,9 @@ The `.mcp.json` file in the project root defines all MCP servers: } } } + +**Note:** Most servers use `mcp_server.server` (local source). +Exception: gitea uses `gitea_mcp.server` (pip-installed package). ``` ### MCP Server Lifecycle diff --git a/plugins/debug-mcp/commands/debug-mcp-inspect.md b/plugins/debug-mcp/commands/debug-mcp-inspect.md index 0fec606..577654c 100644 --- a/plugins/debug-mcp/commands/debug-mcp-inspect.md +++ b/plugins/debug-mcp/commands/debug-mcp-inspect.md @@ -53,6 +53,9 @@ Execute `skills/visual-header.md` with context "Server Inspection". - Args: ["-m", "mcp_server.server"] - CWD: /path/to/mcp-servers/gitea - Env file: ~/.config/claude/gitea.env + +**Note:** The gitea server uses `gitea_mcp.server` (installed from package). +Other servers use `mcp_server.server` (local source). ``` ### Phase 2: Dependencies (--deps) diff --git a/plugins/debug-mcp/commands/debug-mcp-scaffold.md b/plugins/debug-mcp/commands/debug-mcp-scaffold.md index b4b04ed..808696a 100644 --- a/plugins/debug-mcp/commands/debug-mcp-scaffold.md +++ b/plugins/debug-mcp/commands/debug-mcp-scaffold.md @@ -108,6 +108,9 @@ python-dotenv>=1.0.0 "cwd": "mcp-servers/" } ``` + + **Note:** Use `mcp_server.server` for new servers being scaffolded. + Exception: gitea uses `gitea_mcp.server` (pip-installed package). 3. Show the change and ask user to confirm before writing ### Phase 5: Completion diff --git a/plugins/debug-mcp/skills/server-patterns.md b/plugins/debug-mcp/skills/server-patterns.md index 73bd545..0a8135d 100644 --- a/plugins/debug-mcp/skills/server-patterns.md +++ b/plugins/debug-mcp/skills/server-patterns.md @@ -20,6 +20,9 @@ mcp-servers// └── README.md ``` +**Exception:** The gitea server uses the `gitea-mcp` package from Gitea PyPI +instead of local source. Its module is `gitea_mcp`, not `mcp_server`. + ## FastMCP Pattern (Recommended) The FastMCP decorator pattern provides the simplest server implementation: diff --git a/plugins/debug-mcp/skills/venv-diagnostics.md b/plugins/debug-mcp/skills/venv-diagnostics.md index 21d9f88..92f04c3 100644 --- a/plugins/debug-mcp/skills/venv-diagnostics.md +++ b/plugins/debug-mcp/skills/venv-diagnostics.md @@ -55,9 +55,13 @@ This reports broken dependencies (missing or incompatible versions). Verify the server's main module can be imported: ```bash -cd && .venv/bin/python -c "import mcp_server.server" 2>&1 +cd && .venv/bin/python -c "import .server" 2>&1 ``` +Where `` is the server's Python module: +- gitea: `gitea_mcp` (pip-installed package) +- All others: `mcp_server` (local source) + Common failures: | Error | Cause | Fix | |-------|-------|-----| diff --git a/plugins/projman/.doc-guardian-queue b/plugins/projman/.doc-guardian-queue deleted file mode 100644 index 8228a4e..0000000 --- a/plugins/projman/.doc-guardian-queue +++ /dev/null @@ -1,5 +0,0 @@ -2026-01-30T14:32:53 | skills | /home/lmiranda/claude-plugins-work/plugins/projman/skills/setup-workflows.md | README.md -2026-01-30T14:32:53 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/setup.md | docs/COMMANDS-CHEATSHEET.md README.md -2026-01-30T14:32:54 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/debug.md | docs/COMMANDS-CHEATSHEET.md README.md -2026-01-30T14:32:54 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/test.md | docs/COMMANDS-CHEATSHEET.md README.md -2026-01-30T14:33:13 | commands | /home/lmiranda/claude-plugins-work/plugins/projman/commands/sprint-status.md | docs/COMMANDS-CHEATSHEET.md README.md