Skip to content

development.md

Latest commit

 

History

History
230 lines (165 loc) · 6.08 KB

development.md

File metadata and controls

230 lines (165 loc) · 6.08 KB
Raw

Development Guide

Phase 1 Implementation Status

✅ COMPLETE - All Phase 1 features have been implemented!

Implemented Features

  • Server registry with core servers (sequential-thinking, context7, exa, firecrawl, playwright)
  • Basic dependency checking (node, python, uv, docker)
  • ftk init command with interactive wizard
  • Secrets management (.env.mcp.secrets with gitignore integration)
  • .mcp.json generation with dotenv-cli wrapper support
  • CLAUDE.md augmentation with marker-based inline content

Project Structure

fluent-toolkit/
├── src/
│   ├── main.ts                 # CLI entry point
│   ├── commands/               # Command handlers
│   │   └── init.ts             # ftk init implementation
│   ├── core/                   # Core modules
│   │   ├── registry.ts         # MCP server registry
│   │   ├── config.ts           # Config read/write
│   │   ├── dependencies.ts     # Dependency checking
│   │   ├── secrets.ts          # .env.mcp.secrets management
│   │   └── claude-md.ts        # CLAUDE.md augmentation
│   ├── services/               # Service layer
│   │   └── template-renderer.ts # Template rendering
│   ├── ui/                     # User interface
│   │   └── prompts.ts          # Interactive prompts
│   └── types/                  # TypeScript definitions
│       └── index.ts            # Type definitions
├── registry/
│   ├── index.ts                # Registry discovery
│   └── mcp-servers/            # Modular server definitions
│       ├── sequentialthinking/
│       ├── context7/
│       ├── exa/
│       └── basic-memory/
├── Formula/                    # Homebrew formula
│   └── fluent-toolkit.rb
├── docs/                       # Documentation
│   ├── README.md               # Documentation index
│   ├── archive/                # Historical documents
│   │   ├── design.md           # Design decisions
│   │   ├── research.md         # Research notes
│   │   └── refactoring.md      # Refactoring summary
│   └── ...
├── deno.json                   # Deno configuration
├── README.md                   # Project documentation
├── CLAUDE.md                   # AI assistant instructions
└── context/                    # AI context directory (gitignored)

Development Commands

Run in development mode

deno task dev

Run ftk init

deno task dev init

Run with options

deno task dev init --help
deno task dev init --force
deno task dev init --skip-validation
deno task dev init --servers sequential-thinking,context7

Compile binary

deno task compile

This creates bin/ftk executable.

Format code

deno task fmt

Lint code

deno task lint

Testing the Implementation

Test with a fresh project

  1. Create a new test directory:
mkdir ~/test-ftk-project
cd ~/test-ftk-project
  1. Run ftk init:
cd ~/src/spantree-fluent/fluent-toolkit
deno task dev init

  1. Follow the interactive prompts to select servers and provide API keys

  2. Verify the generated files:

ls -la ~/test-ftk-project
cat ~/test-ftk-project/.mcp.json
cat ~/test-ftk-project/CLAUDE.md
cat ~/test-ftk-project/.env.mcp.secrets
cat ~/test-ftk-project/.ftk/config.json
  1. Start Claude Code and verify MCP servers load:
cd ~/test-ftk-project
claude

Implementation Details

Server Registry

The server registry uses a modular architecture where each server is defined in its own directory under registry/mcp-servers/. Available MCP servers:

  • sequential-thinking: Enhanced reasoning (core)
  • context7: Library documentation (core)
  • exa: Web research (optional, requires API key)
  • firecrawl: Web scraping (optional, requires API key)
  • playwright: Browser automation (optional)

Configuration Strategy

Dual-layer configuration:

  • User-level: ~/.ftk/config.json (global preferences)
  • Project-level: .ftk/config.json (project-specific)

MCP configuration:

  • .mcp.json in project root
  • Uses dotenv-cli wrapper for servers requiring secrets

Secrets Management

  • Secrets stored in .env.mcp.secrets (gitignored automatically)
  • dotenv-cli injects secrets at MCP server runtime
  • Prevents credential exposure in version control

CLAUDE.md Strategy

Uses marker-based inline content approach (validated in test project):

<!-- ftk:begin:mcp-overview -->

## MCP Servers Configuration

...

<!-- ftk:end:mcp-overview -->

This allows ftk to manage specific sections without clobbering user content.

Next Steps

Phase 2 (Enhancement)

  • ftk doctor command for diagnostics
  • Advanced validation with custom validators
  • Installation assistance (auto-run install commands)
  • Better error messages
  • Progress indicators for long operations

Phase 3 (Extensibility)

  • ftk update-registry command (git sparse checkout)
  • Registry version compatibility checking
  • Custom server definitions (local registry)

Phase 4 (Plugin Generation)

  • ftk plugin create command
  • Bundle MCP servers + slash commands + hooks
  • ftk plugin publish for marketplace

Phase 5 (Agent SDK Integration)

  • ftk agent create command
  • Agent loop templates
  • Deep Researcher agent
  • Writing Coach agent

Contributing

When adding new features:

  1. Update type definitions in src/types/index.ts
  2. Implement core functionality in appropriate module
  3. Add CLI command in src/commands/
  4. Update registry if adding new servers
  5. Test manually before committing
  6. Update this document with new features

Architecture Decisions

See archive/design.md for detailed architecture decisions and rationale.

Research Background

See archive/research.md for research on Claude Code plugins, Agent SDK, and CLAUDE.md behavior.