docs: Add CLAUDE.md for Claude Code guidance

[bearmug]

Summary

• Add CLAUDE.md documentation file for Claude Code integration
• Includes build/dev commands, architecture overview, and extension guides
• Helps future Claude Code sessions understand the project structure quickly

Test plan

• Verify CLAUDE.md renders correctly on GitHub
• Confirm file follows the expected format for Claude Code

🤖 Generated with Claude Code

[claude]

Pull Request Review: CLAUDE.md Documentation

Overall Assessment

Verdict: Approve with minor suggestions ✅

This is an excellent documentation addition that will significantly help Claude Code understand and work with this codebase. The documentation is accurate, well-structured, and comprehensive.

---

Strengths

1. Accuracy ✓

• All build commands match package.json scripts exactly
• Architecture description aligns perfectly with the actual code structure in src/index.ts
• Tool descriptions accurately reflect the 8 MCP tools registered in the server
• Configuration variables (CACHE_TTL_SECONDS, RATE_LIMIT_RPM) match the implementation in src/index.ts:25-26

2. Completeness ✓

• Covers all critical areas: build/dev commands, architecture, core components, tools, resources, utilities
• Includes practical "Adding New Features" section with concrete steps
• References the Claude Code commands in .claude/commands/

3. Structure ✓

• Well-organized with clear hierarchical sections
• Good balance between high-level overview and implementation details
• Code examples are clear and accurate

---

Minor Suggestions

1. Preset List Accuracy ⚠️
The documentation states presets include: quality, value, dividend, momentum, growth, market_indexes

However, examining src/resources/presets.ts, I found additional presets:

• quality_growth_screener (comprehensive quality+growth screen)
• Other presets beyond the basic five mentioned

Suggestion: Update line 48 to be more accurate:

- `presets.ts` - Pre-configured screening strategies (quality, value, dividend, momentum, growth, quality_growth_screener, market_indexes, etc.). Presets can be filter-based or symbol-based (for direct lookup)

2. Configuration File Location Clarification ℹ️
The documentation mentions:

Environment variables (set in `.mcp.json`):

This could be slightly misleading since environment variables can be set in multiple ways. Based on the README, .mcp.json is the Claude Code config file, but it's also mentioned in claude_desktop_config.json for Claude Desktop.

Suggestion: Clarify:

## Configuration

Environment variables (can be set in MCP server config):
- `CACHE_TTL_SECONDS` - Cache duration (default: 300)
- `RATE_LIMIT_RPM` - Requests per minute (default: 10)

For Claude Code, add these to your `.mcp.json` server configuration:
```json
{
  "mcpServers": {
    "tradingview": {
      "command": "npx",
      "args": ["-y", "tradingview-mcp-server"],
      "env": {
        "CACHE_TTL_SECONDS": "300",
        "RATE_LIMIT_RPM": "10"
      }
    }
  }
}

**3. Minor Enhancement Opportunity** 💡
Consider adding a brief mention of the hot-reload limitation mentioned in the development workflow section, as this is important for developers to know when making changes.

---

### Code Quality Assessment

**No Issues Found:**
- ✅ No security concerns (documentation only)
- ✅ No performance issues
- ✅ No bugs
- ✅ Format and markdown syntax are correct
- ✅ Test coverage: N/A (documentation file)

---

### Best Practices Adherence

The documentation follows excellent practices:
- Clear, concise language
- Accurate technical details verified against actual code
- Practical examples and guidance
- Good organizational structure
- Follows the expected CLAUDE.md format for Claude Code integration

---

### Recommendation

**Approve and merge** with the optional minor suggestions above. The current version is already highly valuable and accurate - the suggestions are truly minor enhancements rather than critical issues.

This documentation will significantly improve Claude Code's ability to work with this project. Great work! 🎉

[claude]

PR Review: CLAUDE.md Documentation

Overall Assessment

This is an excellent addition to the project! The CLAUDE.md file is well-structured, comprehensive, and provides clear guidance for Claude Code integration. The documentation accurately reflects the codebase structure and will be valuable for future development sessions.

Strengths

Comprehensive Coverage

• Clear project overview and purpose
• Complete build and development commands
• Detailed architecture breakdown with file references
• Helpful "Adding New Features" section for common extension patterns
• Proper documentation of all 7 MCP tools exposed

Accuracy

• All mentioned files and directories exist and match the codebase structure
• npm scripts align with package.json (build, dev, test, test:watch)
• Claude Code commands directory correctly referenced (.claude/commands/)
• Component descriptions match the actual implementation
• Configuration variables (CACHE_TTL_SECONDS, RATE_LIMIT_RPM) are accurate

Organization

• Logical flow from overview → commands → architecture → configuration → testing → extending
• Good use of code blocks and formatting
• Clear hierarchical structure

Minor Suggestions

1. Configuration Section Enhancement
   The configuration section mentions .mcp.json but could benefit from a brief example:

   {
     "env": {
       "CACHE_TTL_SECONDS": "300",
       "RATE_LIMIT_RPM": "10"
     }
   }

2. Test Command Clarity
   The "Running a single test file" example uses fields.test.ts which works, but could note that the path prefix isn't needed since the test script already targets src/tests/*.test.ts.

3. API Endpoints Completeness
   The API Layer section mentions /global/scan, /forex/scan, /crypto/scan but could also note /america/scan if it's used for ETF screening.

4. Development Workflow Enhancement
   The workflow mentions "Restart Claude" but could be more specific about restarting Claude Desktop or the MCP server connection.

Code Quality Observations

What's Good:

• No code changes, only documentation
• Pure additive change with zero deletions
• Follows standard CLAUDE.md conventions
• File is properly formatted markdown

No Issues Found:

• No bugs introduced
• No performance concerns (documentation only)
• No security concerns
• No test coverage impact

Verification

I verified the following claims in the documentation:

• ✅ All file paths and directory structure match the codebase
• ✅ npm scripts exist as documented
• ✅ MCP tools count and names are accurate
• ✅ Claude Code commands exist in .claude/commands/
• ✅ Architecture component descriptions match implementation
• ✅ STOCK_FIELDS reference is correct
• ✅ Configuration variables are accurate

Recommendation

APPROVE - This PR is ready to merge. The suggestions above are minor enhancements that could be addressed in a follow-up if desired, but they don't block merging this valuable documentation.

The CLAUDE.md file will significantly improve the Claude Code development experience by providing immediate context about the project structure, conventions, and common tasks.

---

Review generated by Claude Code