# ◈──◆──◇ AI TOOL MCP SERVER ◇──◆──◈
**Alternative Package Name** - This package (`@nbiish/ai-tool-mcp`) is an alias/alternative name for [`@nbiish/giizhendam-aabajichiganan-mcp`](https://www.npmjs.com/package/@nbiish/giizhendam-aabajichiganan-mcp). Both packages provide identical functionality.
*"Giizhendam Aabajichiganan"* (Ojibwe: Decision-Making Tools) - An MCP server providing AI-assisted programming and decision-making tools.
╭──────────────[ ◈◆◇ SYSTEM OVERVIEW ◇◆◈ ]──────────────╮
## ᐴ WAAWIINDAMAAGEWIN ᔔ [OVERVIEW] ◈──◆──◇──◆──◈
This project implements a Model Context Protocol (MCP) server that provides multi-agent CLI orchestration for developers and decision-makers. It serves as a bridge between different AI models and external CLI agents, and provides specialized tools for financial analysis and collaborative decision simulation.
The server includes a multi-agent orchestrator tool (`orchestrate_agents`) that loads CLI agents from `CLI_AGENTS_JSON` or `llms.txt`, uses a configurable orchestrator model (default: Gemini 2.5 Pro) via OpenRouter to decide between sequential or parallel execution, executes the agents, and synthesizes a consolidated markdown report.
**Key Features:**
- **Unified Orchestrator Model**: All AI operations use a single configurable model via OpenRouter
- **18 Financial Expert Agents**: Comprehensive financial analysis with individual expert perspectives (900 tokens each) + RAG consolidation
- **Model Flexibility**: Easily swap between any OpenRouter-supported model (Gemini, Claude, GPT-4, etc.)
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
## ᐴ GASHKITOONAN ᔔ [CAPABILITIES] ◈──◆──◇──◆──◈
- **◇ Multi-Agent Orchestrator ◇**
- Load CLI agents from CLI_AGENTS_JSON or llms.txt
- Model-chosen sequential or parallel execution
- Consolidated markdown synthesis of agent outputs
- **◇ Financial Expert Simulation ◇**
- Orchestrates 18 financial expert agents individually (900 tokens each)
- Uses orchestrator model with File Search RAG to consolidate all expert outputs
- Generates enterprise-ready, production-grade analysis and strategic advisory
- Includes perspectives from: Damodaran, Graham, Buffett, Munger, Lynch, Fisher, Ackman, Wood, Burry, Pabrai, Jhunjhunwala, Druckenmiller, plus Valuation, Sentiment, Fundamentals, Technicals, Risk Manager, and Portfolio Manager agents
- **◇ CEO & Board Meeting Simulation ◇**
- Simulates realistic board discussions on specified topics
- Customizable roles and discussion parameters
- Useful for planning and decision-making exercises
- **◇ Security & Reliability ◇**
- Built-in security checks for file operations and URL validation
- Comprehensive error handling and logging
- Secure API key management
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
## ᐴ OSHKI-AABAJICHIGANAN ᔔ [RECENT CHANGES] ◈──◆──◇──◆──◈
- **v0.6.0** - **Major Refactor**: Unified orchestrator model configuration via OpenRouter. Removed direct Gemini API dependency. All AI operations now use a single configurable model (`ORCHESTRATOR_MODEL`). Enhanced financial experts tool with 18 agents, 900-token limits, and RAG consolidation. Supports any OpenRouter model (Gemini, Claude, GPT-4, etc.).
- **v0.5.3** - Added 18 financial expert agents with dynamic prompt loading from markdown files
- **v0.3.34** - Fixed shebang line in the bundled output file to ensure proper execution via npx. This resolves issues with "Client closed" errors when running via MCP.
◈──◆──◇─────────────────────────────────────────────────◇──◆──◈
## ᐴ NITAM-AABAJICHIGANAN ᔔ [PREREQUISITES] ◈──◆──◇──◆──◈
- Node.js (v14 or higher) and npm/yarn
- CLI tools for agents you plan to run (e.g., qwen, gemini, cursor, goose, opencode, crush) available in PATH
- **OpenRouter API Key** (required) - Used for all AI operations
- **ORCHESTRATOR_MODEL** (optional) - Defaults to `google/gemini-2.5-pro`, can be any OpenRouter-supported model
╭──────────────[ ◈◆◇ SYSTEM INSTALLATION ◇◆◈ ]──────────────╮
## ᐴ AABAJITOOWINAN ᔔ [INSTALLATION] ◈──◆──◇──◆──◈
### Global Installation (Recommended)
```bash
╭──────────────────────────────────────────────────────────────────────╮
│ ᐴ AABAJITOOWINAN ᔔ [ IMPLEMENTATION COMMANDS ] │
╰──────────────────────────────────────────────────────────────────────╯
# Install via npx (recommended for MCP)
npx -y @nbiish/ai-tool-mcp
# Or install globally from npm registry
npm install -g @nbiish/ai-tool-mcp
# Alternative: Use the main package name (identical functionality)
npm install -g @nbiish/giizhendam-aabajichiganan-mcp
```
### Troubleshooting Installation Issues
If you encounter issues with the executable script (e.g., "command not found" or shell syntax errors), try these steps:
```bash
╭──────────────────────────────────────────────────────────────────────╮
│ ᐴ NANAA'ITOOWIN ᔔ [ TROUBLESHOOTING COMMANDS ] │
╰──────────────────────────────────────────────────────────────────────╯
# Check if the installed script has the proper shebang line:
cat $(which ai-tool-mcp)
# Alternatively, reinstall after clearing npm cache:
npm cache clean --force
npm uninstall -g @nbiish/ai-tool-mcp
npm install -g @nbiish/ai-tool-mcp
```
╭──────────────[ ◈◆◇ SYSTEM CONFIGURATION ◇◆◈ ]──────────────╮
## ᐴ ONAAKONIGE ᔔ [CONFIGURATION] ◈──◆──◇──◆──◈
### MCP Client Configuration (`mcp.json`)
Configure the server in your MCP client's configuration file. The location depends on your client:
- **Cursor**: `~/.cursor/mcp.json` or `~/.config/cursor/mcp.json`
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Other MCP Clients**: Check your client's documentation
#### Basic Configuration (Recommended)
```json
{
"mcpServers": {
"ai-tool-mcp": {
"command": "npx",
"args": ["-y", "@nbiish/ai-tool-mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"ORCHESTRATOR_MODEL": "google/gemini-2.5-pro"
}
}
}
}
```
#### Full Configuration with All Options
```json
{
"mcpServers": {
"ai-tool-mcp": {
"command": "npx",
"args": ["-y", "@nbiish/ai-tool-mcp"],
"env": {
"OPENROUTER_API_KEY": "sk-or-v1-your-key-here",
"ORCHESTRATOR_MODEL": "google/gemini-2.5-pro",
"CLI_AGENTS_JSON": "[{\"name\":\"Qwen\",\"cmd\":\"qwen -y \\\"{prompt}\\\"\"},{\"name\":\"Gemini\",\"cmd\":\"gemini -y \\\"{prompt}\\\"\"}]",
"AGENT_OUTPUT_DIR": "./output/agents",
"EXECUTION_STYLE": "auto",
"FINANCE_EXPERTS_OUTPUT_DIR": "./output/finance-experts",
"CEO_BOARD_OUTPUT_DIR": "./output/ceo-and-board",
"OPENROUTER_TIMEOUT_MS": "30000",
"SYNTH_MAX_PER_AGENT_CHARS": "20000",
"SYNTH_MAX_TOTAL_CHARS": "150000"
}
}
}
}
```
### Environment Variables Reference
#### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `OPENROUTER_API_KEY` | Your OpenRouter API key (required for all AI operations) | `sk-or-v1-...` |
#### Optional Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `ORCHESTRATOR_MODEL` | `google/gemini-2.5-pro` | Model used for all AI operations. Can be any OpenRouter-supported model (see below) |
| `CLI_AGENTS_JSON` | (none) | JSON array of CLI agent definitions (see CLI Agents section) |
| `AGENT_OUTPUT_DIR` | `./output/agents` | Directory for orchestrator tool outputs |
| `EXECUTION_STYLE` | `auto` | Execution style: `auto` (model decides), `sequential`, or `parallel` |
| `FINANCE_EXPERTS_OUTPUT_DIR` | `./output/finance-experts` | Directory for financial expert analysis outputs |
| `CEO_BOARD_OUTPUT_DIR` | `./output/ceo-and-board` | Directory for board simulation outputs |
| `OPENROUTER_TIMEOUT_MS` | `30000` | Timeout for OpenRouter API calls (milliseconds) |
| `SYNTH_MAX_PER_AGENT_CHARS` | `20000` | Max characters per agent in synthesis |
| `SYNTH_MAX_TOTAL_CHARS` | `150000` | Max total characters in synthesis |
### Orchestrator Model Options
The `ORCHESTRATOR_MODEL` can be any model supported by OpenRouter. Popular options:
**Google Models:**
- `google/gemini-2.5-pro` (default, recommended for best quality)
- `google/gemini-2.0-flash-exp` (faster, cheaper, good for testing)
- `google/gemini-1.5-pro` (alternative)
- `google/gemini-1.5-flash` (fastest, cheapest)
**Anthropic Models:**
- `anthropic/claude-3.5-sonnet` (high quality alternative)
- `anthropic/claude-3-opus` (premium quality)
- `anthropic/claude-3-haiku` (fast, cost-effective)
**OpenAI Models:**
- `openai/gpt-4-turbo` (alternative)
- `openai/gpt-4` (alternative)
- `openai/gpt-3.5-turbo` (budget option)
**Other Providers:**
- `meta-llama/llama-3.1-405b-instruct` (open source)
- `mistralai/mixtral-8x7b-instruct` (open source)
For complete details and testing guidance, see the [main package documentation](https://github.com/nbiish/giizhendam-aabajichiganan-mcp/blob/main/ORCHESTRATOR_MODEL_CONFIG.md).
### CLI Agents Configuration
Configure CLI agents for the `orchestrate_agents` tool in two ways:
#### Option A: Using CLI_AGENTS_JSON (Recommended)
Set the `CLI_AGENTS_JSON` environment variable as a JSON array:
```json
[
{"name": "Qwen", "cmd": "qwen -y \"{prompt}\""},
{"name": "Gemini", "cmd": "gemini -y \"{prompt}\""},
{"name": "Cursor", "cmd": "cursor agent --print --approve-mcps \"{prompt}\""},
{"name": "Goose", "cmd": "echo \"{prompt}\" | goose"},
{"name": "Opencode", "cmd": "opencode run \"{prompt}\""},
{"name": "Crush", "cmd": "crush run \"{prompt}\""}
]
```
**Important:** Escape quotes properly in JSON:
- Use `\"` for double quotes inside strings
- Use `\\\"` for quotes inside command strings
#### Option B: Using llms.txt (Fallback)
If `CLI_AGENTS_JSON` is not set, the server reads `llms.txt` from the current working directory:
```
- Qwen
```bash
qwen -y "{prompt}"
```
- Gemini
```bash
gemini -y "{prompt}"
```
- Cursor
```bash
cursor agent --print --approve-mcps "{prompt}"
```
```
### Important Notes
⚠️ **Security:**
- Never commit your `mcp.json` file with real API keys to version control
- Use environment variables or secret management tools in production
- The `GEMINI_API_KEY` environment variable is **no longer used** (removed in v0.6.0)
⚠️ **Breaking Changes (v0.6.0):**
- Removed `GEMINI_API_KEY` requirement - all operations now use OpenRouter
- Removed `@google/generative-ai` dependency
- All AI calls now go through OpenRouter with the orchestrator model
╭──────────────[ ◈◆◇ SYSTEM OPERATION ◇◆◈ ]──────────────╮
## ᐴ INAABAJICHIGAN ᔔ [USAGE] ◈──◆──◇──◆──◈
### Orchestrate CLI Agents
Use the `orchestrate_agents` tool to run your configured CLI agents and produce a consolidated report:
```typescript
╭──────────────────────────────────────────────────────────────────────╮
│ ᐴ WIIDOOKAAZOWIN ᔔ [ CODE ASSISTANCE ] │
╰──────────────────────────────────────────────────────────────────────╯
const result = await server.execute("orchestrate_agents", {
prompt_text: "Create a React component that displays a counter with increment and decrement buttons"
});
// Returns a summary with execution style, per-agent outputs, and synthesis markdown path in _meta
```
### Financial Expert Simulation
Orchestrates 18 financial expert agents individually, then uses the orchestrator model with File Search RAG to consolidate all perspectives into enterprise-ready analysis:
```typescript
╭──────────────────────────────────────────────────────────────────────╮
│ ᐴ ZHOONIYAAWICHIGEWIN ᔔ [ FINANCIAL EXPERTISE ] │
╰──────────────────────────────────────────────────────────────────────╯
const result = await server.execute("finance_experts", {
topic: "Funding strategy for our new AI product line",
output_filename: "ai_product_funding_analysis" // Optional: custom filename
});
// Process:
// 1. Each of 18 experts provides analysis (900 tokens each)
// 2. Individual expert files saved to expert_outputs_[timestamp]/
// 3. Orchestrator model consolidates all outputs using File Search RAG
// 4. Results saved to ./finance-experts/ai_product_funding_analysis_[timestamp].md
// - Includes all individual expert perspectives
// - Includes consolidated RAG-based analysis
// - Includes recommended orchestrator prompt for CLI tools
```
### Board Meeting Simulation
Simulate a board discussion on a specific topic:
```typescript
╭──────────────────────────────────────────────────────────────────────╮
│ ᐴ MAAWANJIDIWIN ᔔ [ BOARD MEETING ] │
╰──────────────────────────────────────────────────────────────────────╯
const result = await server.execute("ceo_and_board", {
topic: "Q3 Strategy Review: Expansion into European Markets",
output_filename: "q3_europe_expansion_board_meeting" // Optional: custom filename
});
// The tool now uses standard board roles by default, including:
// Board Chair, CEO, CFO, COO, CTO, Independent Director, Corporate Secretary/General Counsel, etc.
// You can also specify custom roles if needed:
const result = await server.execute("ceo_and_board", {
topic: "Q3 Strategy Review: Expansion into European Markets",
roles: ["CEO", "CFO", "CTO", "Lead Investor", "Independent Director"],
output_filename: "q3_europe_expansion_board_meeting"
});
// Results saved to the configured output directory or default ./ceo-and-board/
```
## Tool Reference
### orchestrate_agents
| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| prompt_text | string | The main prompt/instruction that is passed to each CLI agent's command template | Yes |
### finance_experts
| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| topic | string | The central financial topic or query related to a project or business situation | Yes |
| output_filename | string | Optional filename (without extension) for the output markdown file | No |
### ceo_and_board
| Parameter | Type | Description | Required |
|-----------|------|-------------|----------|
| topic | string | The central topic for the board discussion | Yes |
| roles | string[] | Optional list of board member roles to simulate. If not provided, standard board roles will be used | No |
| output_filename | string | Optional filename (without extension) for the output markdown file | No |
## Package Information
**This package (`@nbiish/ai-tool-mcp`) is an alias/alternative name for the main package.**
- **Main Package**: [`@nbiish/giizhendam-aabajichiganan-mcp`](https://www.npmjs.com/package/@nbiish/giizhendam-aabajichiganan-mcp)
- **GitHub Repository**: [https://github.com/nbiish/giizhendam-aabajichiganan-mcp](https://github.com/nbiish/giizhendam-aabajichiganan-mcp)
- **Both packages provide identical functionality** - use whichever name you prefer!
## License
This project is licensed under the terms specified in the [LICENSE](https://github.com/nbiish/giizhendam-aabajichiganan-mcp/blob/main/LICENSE) file. This license is a COMPREHENSIVE RESTRICTED USE LICENSE FOR INDIGENOUS CREATIONS WITH TRIBAL SOVEREIGNTY, DATA SOVEREIGNTY, AND WEALTH RECLAMATION PROTECTIONS.
## Contributing
Please read [CONTRIBUTING.md](https://github.com/nbiish/giizhendam-aabajichiganan-mcp/blob/main/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
## More Information
For complete documentation, examples, and detailed configuration options, please visit the [main package repository](https://github.com/nbiish/giizhendam-aabajichiganan-mcp).
Copyright © 2025 ᓂᐲᔥ ᐙᐸᓂᒥᑮ-ᑭᓇᐙᐸᑭᓯ (Nbiish Waabanimikii-Kinawaabakizi), also known legally as JUSTIN PAUL KENWABIKISE, professionally documented as Nbiish-Justin Paul Kenwabikise, Anishinaabek Dodem (Anishinaabe Clan): Animikii (Thunder), a descendant of Chief ᑭᓇᐙᐸᑭᓯ (Kinwaabakizi) of the Beaver Island Band, and an enrolled member of the sovereign Grand Traverse Band of Ottawa and Chippewa Indians. This work embodies Traditional Knowledge and Traditional Cultural Expressions. All rights reserved.
