A plugin is a Python module containing one or more functions decorated with mcp_tool(name, description, input_schema). The misc MCP server discovers decorated functions and exposes them as MCP tools; the module does not construct an MCP Server.
Paths And Modes
- MISC_MCP_DEV_MODE=1 enables external plugin directories and /home/john/py/mcp-tools. Production mode loads built-in tools only.
- MISC_MCP_TOOL_PATH is a colon-separated search path on Linux; MISC_MCP_EXTRA_TOOL_PATH may append trusted development directories.
- MISC_MCP_DEBUG_TRACEBACKS=1 includes module and full traceback fields in client errors during controlled development. Full traces are logged server-side by default.
- The runtime launcher is /home/john/py/gdata-server/start_misc_server.sh. The /etc/rcs/misc-mcp child deliberately uses MISC_MCP_DEV_MODE=0.
Minimal Plugin
Handler argument names must match the inputSchema property names. Return a JSON-serializable value; non-string values are encoded automatically and strings are returned as-is. Sync and async handlers are supported.
Reload And Errors
- Discovery reads and compiles current source content, so edits are detected without restart or stale .pyc behavior.
- The loader keeps the last-known-good plugin export if a changed module has a syntax/import failure.
- Broken modules are logged and skipped. Duplicate names use the first search directory.
- Handler failures return structured status=error, tool, exception_type, and message data. Full traceback fields require MISC_MCP_DEBUG_TRACEBACKS=1.
Side Effects And Testing
Plugins execute in the MCP server process with that process's credentials. Supervised development execution is an accepted operator policy, but development mode should remain manually enabled and observed. Test plugins with python -m unittest -v test_mcp_tool_plugins.py; the current suite has 30 passing tests.
References
Implementation: mcp_tool_plugins.py. Mailbox example: mailbox_tools.py. Tracked dev_file implementation: dev_plugins/dev_file_tools.py. Runtime wrapper: /home/john/py/mcp-tools/dev_file_tools.py. Development-file operations are documented in popit3/mcp-dev-file-tool.