Stock Buddy Skills Suite

A comprehensive suite of AI-powered stock analysis tools for the Dhaka Stock Exchange (DSE), built on the MCP (Model Context Protocol) framework.

🚀 Quick Start

Using npx (Node.js)

npx @stock-buddy/mcp-server

Using Docker

docker-compose up -d

Manual Installation

# Clone the repository
git clone https://github.com/kuntal-r-d/my-skills.git
cd my-skills

# Install Node.js dependencies and build
npm ci
npm run build
npm run build:skills-cli

# Restore shared market-data SQLite from data/stockbuddy.sqlite.gz
# (live DB files are gitignored — other machines need this step)
cp .env.example .env   # DATABASE_URL=file:data/stockbuddy.sqlite
npm run db:restore-snapshot

# Run the server (stdio)
npm start
# or: npx stock-buddy-mcp

Database on a new machine

Live SQLite (data/stockbuddy.sqlite) is not in git. The portable snapshot is data/stockbuddy.sqlite.gz.

# from repo root — removes local DB, unpacks .gz, runs migrations
npm run db:restore-snapshot

Equivalent manual steps:

rm -f data/stockbuddy.sqlite data/stockbuddy.sqlite-* data/stockbuddy.export.sqlite
gunzip -k data/stockbuddy.sqlite.gz
npm run db:migrate

To refresh the snapshot for others (on a machine with up-to-date data):

gzip -c data/stockbuddy.sqlite > data/stockbuddy.sqlite.gz
git add data/stockbuddy.sqlite.gz
git commit -m "chore: refresh shared SQLite market-data snapshot"
git push

📦 Features

14 Specialized Analysis Skills

daily-briefing - Pre-market briefing with portfolio alerts
financial-terms-educator - Educational explanations of financial concepts
fundamental-analysis - Company financial evaluation
macro-regime - Economic environment assessment
momentum-screen - 25-point momentum checklist
pattern-miner - Price pattern recognition
risk-manager - Portfolio risk assessment
sentiment-news - Market sentiment analysis
signal-synthesizer - Multi-signal aggregation
smart-money-flow - Institutional flow tracking
stock-screener - Market-wide screening
technical-analysis - Technical indicators
ticker-dossier - Comprehensive stock profiles
value-investment-checklist - 30-point value criteria

Composite Tools

analyze_ticker - Full pipeline analysis for a single stock
screen_market - Market-wide screening and ranking

🛠️ Architecture

Technology Stack

Skills: TypeScript (compiled Node.js CLIs)
MCP Server: TypeScript with @modelcontextprotocol/sdk
Transports: stdio (default) and HTTP
Data: Pluggable data adapter with caching (@stock-buddy/data-adapter)

Project Structure

stock-buddy/
├── packages/              # TypeScript monorepo
│   ├── core/              # Shared types, indicators, DSE config
│   ├── skills/            # All 14 skill implementations
│   ├── mcp-server/        # MCP server
│   ├── data-adapter/      # Data provider abstraction
│   ├── agents/            # Multi-agent orchestration
│   ├── prediction/        # Price target engine
│   ├── ui/                # HTML checklist generator
│   └── scraper/           # DSE data fetchers
├── skills/                # SKILL.md + compiled CLI scripts
├── tests/                 # Vitest integration tests
└── docs/                  # Documentation

🔧 Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "stock-buddy": {
      "command": "python3",
      "args": ["-m", "stock_buddy_mcp.server"],
      "cwd": "/path/to/stock-buddy/mcp-server"
    }
  }
}

Environment Variables

STOCK_BUDDY_HTTP=1 - Enable HTTP transport
STOCK_BUDDY_PORT=8080 - HTTP port (default: 8080)
STOCK_BUDDY_SKILLS_DIR - Path to skills directory

📊 Data Providers

The system uses a pluggable data adapter architecture:

FileProvider - Reads from JSON fixtures (development)
DSEProvider - Real DSE data (production, stub)
MockProvider - Predictable test data

All providers support caching and rate limiting.

🧪 Testing

Run the test suite:

# Unit tests
python -m pytest tests/

# Test individual skills
python skills/momentum-screen/scripts/screen.py --input fixtures/sample.json

# Test data adapter
python test_data_adapter.py

🚢 Deployment

Docker

# Build image
docker build -f mcp-server/Dockerfile -t stock-buddy-mcp .

# Run container
docker run -p 8080:8080 stock-buddy-mcp

Docker Compose

docker-compose up -d

📝 Development

Adding a New Skill

Create skill directory: skills/your-skill/
Add SKILL.md with metadata
Implement logic in scripts/
Add to registry in mcp-server/stock_buddy_mcp/registry.py

Running Locally

# Install in development mode
pip install -e mcp-server/

# Run with stdio transport
python -m stock_buddy_mcp.server

# Run with HTTP transport
STOCK_BUDDY_HTTP=1 python -m stock_buddy_mcp.server

🔒 Security

All outputs include educational disclaimers
No API keys or credentials in code
Rate limiting on all data providers
Docker runs as non-root user
Regular dependency scanning via Dependabot

📄 License

MIT License - See LICENSE file for details.

⚠️ Disclaimer

Educational analysis only. Not financial advice.

This software provides educational analysis of publicly available market data. It does not constitute financial advice. Always consult qualified financial professionals before making investment decisions.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit PRs to the develop branch.

📞 Support

Issues: GitHub Issues
Documentation: docs/

Built with ❤️ for the Dhaka Stock Exchange community

My Skills

README