7134-easy

easy-mcp-server watches the api/ directory and turns each file into MCP tools, REST endpoints, and accompanying OpenAPI/Swagger definitions. When you place an API handler such as api/users/get.ts, the server exposes an MCP tool named api__users__get and a REST route GET /users. It also generates request/response schemas that feed OpenAPI docs and Swagger UI, and can generate n8n nodes that mirror your APIs so you can orchestrate calls in workflows. The system is designed for hot-reloading with zero config; as you add or modify files in api/, the exposed tools and routes update automatically. The example quick start shows starting the stack with npx easy-mcp-server, then using the provided MCP endpoint on port 8888, the REST API on 8887, and Swagger UI and OpenAPI docs at 8887/docs and 8887/openapi.json respectively. You can also refresh n8n nodes via npm run n8n:generate to keep your automation nodes in sync with your API surface.

Prerequisites:

• Node.js and npm installed on your system
• Basic familiarity with your project structure and the MCP concept

Installation steps:

1. Ensure Node.js/npm are installed. Verify:

node -v
npm -v

2. Install or run via npx using the repository package name (no local install required):

npx easy-mcp-server init my-project

3. Navigate into your project and start the stack using the provided scripts:

cd my-project
./start.sh

4. To refresh n8n nodes after making API changes:

npm run n8n:generate

5. To stop the stack:

./stop.sh

Note: The MCP server is designed to work with an api/ folder in your project. If you customize ports, you can set environment variables as described in the configuration notes (e.g., EASY_MCP_SERVER_PORT, EASY_MCP_SERVER_MCP_PORT).

Environment variables and configuration tips:

• EASY_MCP_SERVER_PORT: REST port (default 8887)
• EASY_MCP_SERVER_MCP_PORT: MCP/Tool port (default 8888)
• EASY_MCP_SERVER_LOG_LEVEL: log verbosity (debug, info, warn, error; default info)
• EASY_MCP_SERVER_API_PATH: folder to watch (default ./api)
• EASY_MCP_SERVER_HOST: host binding (default 0.0.0.0)

Common issues:

• If REST or MCP endpoints fail to bind, ensure the ports are free or override with the EASY_MCP_SERVER_PORT/EASY_MCP_SERVER_MCP_PORT vars.
• Ensure your api/ handlers follow the expected naming conventions (e.g., api/users/get.ts) so the corresponding MCP tool names (api__users__get) are generated correctly.
• When updating dependencies, re-run npm run n8n:generate to align n8n nodes with new API surfaces.
• If using bridge/mcp-bridge.json, hot reload behavior remains active on port 8888 unless disabled.

Troubleshooting tips:

• Check logs under EASY_MCP_SERVER_LOG_LEVEL for errors about missing handlers or invalid TypeScript definitions.
• Verify that your API handler files export a proper handler function and that you’re using the minimal templates described in the README.