__                               
_-_ _,,   ,,            ,,           ,-||-,              ,,        |\   
   -/  )  ||   _        ||          ('|||  )             ||     '   \\  
  ~||_<   ||  < \,  _-_ ||/\       (( |||--)) ,._-_  _-_ ||/\\ \\  / \\ 
   || \\  ||  /-|| ||   ||_<       (( |||--))  ||   ||   || || || || || 
   ,/--|| || (( || ||   || |        ( / |  )   ||   ||   || || || || || 
  _--_-'  \\  \/\\ \\,/ \\,\         -____-    \\,  \\,/ \\ |/ \\  \\/  
 (                                                         _/           
                                                                        

Black Orchid: Hackable scripting engine through an MCP server

Hot-reloadable MCP proxy server for custom Python tools. Safe module loading using importlib (not exec). Auto-discovers tools from Python modules with collision detection.

Built for Claude Code primarily but should work with any other setup that accepts MCP.

It's basically a hackable scripting engine through an MCP server, you can add tools, scripts, etc.

Still highly experimental. Feedback and contributions are welcome!

Features

• Hot-reloadable MCP proxy server
• Safe module loading (importlib, not exec)
• Auto-discovers tools from Python modules
• Collision detection for duplicate function names
• Public and private module support

How It Works

• Scans modules/ (public) and private/modules/ (private) folders
• Loads all .py files as tools
• Each function in a module becomes an MCP tool
• Hot reload without restarting server
• Path validation and syntax checking for security

Installation

claude mcp add --transport stdio Black_Orchid python "absolute/path/to/black_orchid.py"

Note: Requires absolute path to black_orchid.py and fastmcp installed globally, otherwise you will need to change the command.

Available Built-in Tools

System Utils:

• get_os_info() - cross-platform OS detection and system information

Session Utils:

• load_working_preferences() - load collaboration preferences
• save_working_preference(key, value) - save a preference
• get_preference(key) - lookup specific preference

Session Memory:

• remember(key, value) - store ephemeral data for current session
• recall(key) - retrieve stored data
• forget(key) - remove specific memory
• list_memories() - see all stored keys
• clear_all_memories() - clear all session memory

Reload Tools:

• reload_all_modules() - reload all modules from scratch
• reload_module(module_name) - reload specific module
• list_rejected_modules() - debug module loading issues

Creating Your Own Modules

You can create modules and have your own custom utilities, wrap APIs, whatever you can imagine.

Here's how:

1. Create a .py file in modules/ folder
2. Write functions with docstrings
3. Call reload_all_modules() to load new tools
4. Functions become available as MCP tools

Example simple module:

def hello_world():
    """Say hello to the world."""
    return "Hello, World!"

Important Notes:

Helper Functions: Functions starting with _ (underscore) are treated as private helpers and won't be exposed as tools. Use this for internal utilities.

def _helper_function():
    """This won't be exposed as a tool"""
    return "internal use only"

def public_tool():
    """This will be exposed"""
    result = _helper_function()
    return result

Classes: Classes are not directly exposed as tools. To expose class methods, instantiate the class and call methods in a function.

class MyUtility:
    def do_something(self):
        return "result"

# Expose the class method as a tool
def use_my_utility():
    """Use MyUtility class"""
    util = MyUtility()
    return util.do_something()

Module Structure

• modules/ - public tools (committed to git)
• private/modules/ - private tools (gitignored)
• Collision handling: automatic _modulename suffix when function names conflict

Usage Examples

Talking to Claude Code

When you want Claude to use your Black Orchid tools, ask naturally:

"Using your Black Orchid proxy tools, can you call list_proxy_tools?"

Or more specifically:

"Please use the Black Orchid proxy tool 'get_os_info' to check my system"

If you already have mentioned Black Orchid you might not need to do much of this.

Claude will use the use_proxy_tool function automatically. You don't need to know the exact MCP function names - just reference "Black Orchid proxy tools" and describe what you want.

Common Commands

• List available tools: list_proxy_tools()
• Call a tool: use_proxy_tool(tool_id, kwargs)
• Reload after changes: reload_all_modules()
• Check rejected modules: list_rejected_modules()

Example Workflow

1. Create a new module in modules/my_tools.py
2. Ask Claude: "Using Black Orchid, reload all modules"
3. Ask Claude: "List the available Black Orchid proxy tools"
4. Ask Claude: "Use the my_function tool from Black Orchid"

Security

Black Orchid is designed with security in mind, but follows a "trust but verify" approach:

What it does:

• Path validation: All module paths are validated against approved directories (modules/ and private/modules/)
• Prevents directory traversal attacks - modules outside approved directories are rejected
• Safe module loading: Uses importlib (Python's standard module loader), not exec()
• Syntax validation: All modules are parsed with ast.parse() before loading to catch syntax errors
• Rejected modules tracking: Use list_rejected_modules() to see what failed to load and why

What you should do/Best practices:

• Only load modules you trust - Black Orchid executes Python code from your modules
• Review any modules before placing them in modules/ or private/modules/
• Keep your private/modules/ folder truly private (it's gitignored by default)
• Be cautious with third-party modules - verify the code before using

Trust but verify: You're ultimately responsible for what code you choose to load.

Contributing

Contribution and feedback is always welcome. Thank you for reading, please tell me of any feature requests, bugs, or anything else.

Licensing stuff

Copyright 2025 AJ Gonzalez

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.