Conversation
Owner
scottgl9
commented
Jan 17, 2026
scottgl9
commented
- Added built-in MCP server for AI agents
- Also added project prompt markdown files under docs to help agents with utilizing thop
- Implement full MCP server with JSON-RPC protocol support - Add comprehensive tool set for session management, command execution, and file operations - Support MCP resources, prompts, and protocol initialization - Add --mcp flag to run thop as MCP server for AI agent integration - Include complete test suite for MCP functionality - Add extensive documentation for MCP server usage and integration - Enable AI agents to have full control over thop's capabilities through standardized protocol
- Remove redundant file operation tools (readFile, writeFile, listFiles) - Remove redundant environment tools (getEnvironment, setEnvironment) - Remove redundant cwd tools (getCwd, setCwd) - Remove redundant config tools (getConfig, listSessions) - Remove unimplemented job management tools (listJobs, getJobOutput, killJob) - Keep only essential tools: connect, switch, close, status, execute, executeBackground - Update documentation to reflect minimalist design philosophy - Add examples showing how to use execute tool for file ops, env management, etc. - Update tests to match streamlined tool set - Reduces tool count from 17 to 6, improving simplicity and maintainability
- Merge executeBackground into execute tool as optional background parameter - Add 'background' boolean parameter to execute tool (default: false) - Remove separate executeBackground tool from tool list - Update documentation to reflect combined tool - Update tests to expect 5 tools instead of 6 - Simplifies API from 6 tools down to 5 tools - Timeout parameter is ignored when background is true
- Add tests for all tool handlers (connect, switch, close, execute) - Add tests for resource reading (session, config, state) - Add tests for prompt retrieval (deploy, debug, backup) - Add tests for error handling and edge cases - Add tests for protocol methods (initialized, cancelled, progress) - Add tests for send methods (sendError, sendNotification) - Add tests for unknown tools and invalid parameters - Increase coverage from 23.1% to 79.2% - Add helper function createTestServer() to reduce test boilerplate
Prompt templates added ~500-700 tokens per MCP session without providing significant value beyond what natural language requests can achieve. AI agents can directly request operations instead of using predefined templates. Changes: - Remove prompts capability from MCP server initialization - Remove handlePromptsList and handlePromptGet handlers - Remove prompt-related tests - Update MCP.md documentation to remove prompt references - Create docs/MCP_PROMPTS.md with full implementation guide for future reference if domain-specific prompts are needed The implementation is preserved in MCP_PROMPTS.md for teams that need standardized, thop-specific multi-step workflows. Test coverage: 77.1% (down from 79.2% due to removed prompt code)
Created concise documentation for AI agents and researched MCP server
enhancements based on existing SSH MCP implementations.
Agent Documentation (377 lines total):
- docs/THOP_FOR_CLAUDE.md (141 lines)
- Quick detection and core commands
- Complete deployment workflow example
- Common patterns: debug, compare config, multi-server deploy
- Best practices and quick reference table
- docs/THOP_FOR_AGENTS.md (236 lines)
- Platform-agnostic essential guide
- Commands organized by category (session, file, env, jobs)
- 3 workflow examples (deploy, compare, multi-server)
- Do/don't examples for common pitfalls
- docs/AGENT_README.md (80 lines)
- Usage instructions and integration examples
- Explains simplified approach for reduced token usage
Design philosophy: Focus on what agents need to know, not
comprehensive documentation. Quick reference format optimized
for agents to read when copied to project directories.
MCP Improvements Research:
- docs/MCP_IMPROVEMENTS.md (362 lines)
- Analyzed tufantunc/ssh-mcp, AiondaDotCom/mcp-ssh,
official MCP filesystem server, and best practices
- 11 specific improvements across 4 priority tiers
- 4-phase implementation roadmap with code examples
Top recommendations:
1. SSH config auto-discovery (~/.ssh/config, known_hosts)
2. Command timeout handling (default 300s, configurable)
3. Structured error codes (SESSION_NOT_FOUND, AUTH_FAILED, etc.)
4. File transfer tools (SCP-based upload/download)
5. Read-only file operations (read_file, list_directory, etc.)
Updated Files:
- README.md: Added "Integration with AI Agents" section with
instructions to copy docs to project directories
- TODO.md: Added MCP server section referencing improvements
Usage: Copy THOP_FOR_CLAUDE.md or THOP_FOR_AGENTS.md to your
project directory so AI agents have the context they need to
effectively use thop for multi-server workflows.
Added comprehensive error handling and flexible timeout configuration to
improve AI agent integration and prevent hung connections.
Structured Error Codes:
- thop-go/internal/mcp/errors.go (179 lines)
- MCPError type with Code, Message, Session, Suggestion fields
- 21 error codes across 5 categories:
* Session: SESSION_NOT_FOUND, SESSION_NOT_CONNECTED, NO_ACTIVE_SESSION, CANNOT_CLOSE_LOCAL
* Connection: AUTH_KEY_FAILED, AUTH_PASSWORD_FAILED, HOST_KEY_UNKNOWN, CONNECTION_TIMEOUT, CONNECTION_REFUSED
* Command: COMMAND_TIMEOUT, COMMAND_NOT_FOUND, PERMISSION_DENIED, COMMAND_FAILED
* Parameter: MISSING_PARAMETER, INVALID_PARAMETER
* Feature: NOT_IMPLEMENTED, OPERATION_FAILED
- Helper constructors with actionable suggestions
- ToToolResult() for consistent MCP responses
- thop-go/internal/mcp/errors_test.go (151 lines)
- Comprehensive error code testing
- Constructor and format validation
Command Timeout Handling:
- thop-go/internal/config/config.go
- Added CommandTimeout field to Session struct
- GetTimeout() method with priority hierarchy:
1. Session-specific timeout
2. Global setting timeout
3. Default 300 seconds
- thop-go/internal/mcp/tools.go
- Updated all tools to use structured errors
- Intelligent error detection via string matching
- Execute tool timeout hierarchy:
1. Explicit timeout parameter
2. Session-specific config
3. Global config
4. Default (300s)
- All errors include actionable suggestions
Documentation:
- docs/MCP.md
- New "Error Codes" section with complete reference
- "Configuration" section with timeout examples
- Updated execute tool with timeout behavior
- Examples for all configuration levels
- Priority order documentation
Features:
- Programmatic error handling for AI agents
- Actionable suggestions for error resolution
- Global, per-session, and per-command timeout control
- Prevents hung connections
- Graceful timeout with structured errors
Example Timeout Configuration:
```toml
[settings]
command_timeout = 300
[sessions.slow-server]
command_timeout = 600
```
Example Error Response:
```json
{
"content": [{
"type": "text",
"text": "[AUTH_KEY_FAILED] SSH key authentication failed\n\nSuggestion: Use /auth to provide a password\n\nSession: prod"
}],
"isError": true
}
```
Benefits:
- AI agents can handle errors programmatically
- Flexible timeout for different server/command needs
- Clear, actionable error messages
- Consistent error format across all tools
- Follows MCP best practices
Test Coverage: 71.8% (all tests passing)
This implements Priority 2 and Priority 3 from docs/MCP_IMPROVEMENTS.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.