Go to Qiita Advent Calendar Top
LoginSignup
3
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@awakia(Naoyoshi Aikawa)

Kiroが立ててくれたgithub mcpを設定するだけの計画メモ

Last updated at Posted at 2025-07-22

Kiro使ってますか？

Kiro設計がいいという話だったので使ってみました。
最近は順番待ちでインストールできないらしいですね。

まずはgithubのIssueを読みたかったので、それをやってもらいたいだけだったのですが、それだけでもかなりの計画を立ててくれたのでメモを残しておこうと思います。

image.png

以下 .kiro/specs/github-mcp-server-setup/ の中にできた計画の中身を書いておきます。

requirements.md

requirements.md
# Requirements Document

## Introduction

This feature enables users to configure and set up a GitHub MCP (Model Context Protocol) server in their Kiro workspace. The GitHub MCP server will allow Kiro to interact with GitHub repositories, issues, pull requests, and other GitHub resources through the MCP protocol, providing seamless integration between the development environment and GitHub services.

## Requirements

### Requirement 1

**User Story:** As a developer, I want to configure a GitHub MCP server in my Kiro workspace, so that I can access GitHub repositories and resources directly from within Kiro.

#### Acceptance Criteria

1. WHEN a user requests GitHub MCP server setup THEN the system SHALL create or update the MCP configuration file with GitHub server settings
2. WHEN the GitHub MCP server is configured THEN the system SHALL include proper authentication settings for GitHub API access
3. WHEN the configuration is complete THEN the system SHALL validate that the GitHub MCP server can be successfully connected

### Requirement 2

**User Story:** As a developer, I want the GitHub MCP server to be properly authenticated, so that I can access private repositories and perform authenticated operations.

#### Acceptance Criteria

1. WHEN configuring the GitHub MCP server THEN the system SHALL prompt for or configure GitHub authentication credentials
2. WHEN authentication is set up THEN the system SHALL securely store the credentials in the appropriate configuration
3. WHEN the server connects THEN the system SHALL verify that authentication is working correctly

### Requirement 3

**User Story:** As a developer, I want the GitHub MCP server configuration to follow best practices, so that it integrates seamlessly with my existing Kiro setup.

#### Acceptance Criteria

1. WHEN adding the GitHub MCP server THEN the system SHALL use the standard uvx command for server execution
2. WHEN configuring the server THEN the system SHALL set appropriate environment variables and logging levels
3. WHEN the configuration is complete THEN the system SHALL ensure the server is enabled and ready for use

### Requirement 4

**User Story:** As a developer, I want to be able to test the GitHub MCP server after setup, so that I can verify it's working correctly.

#### Acceptance Criteria

1. WHEN the GitHub MCP server is configured THEN the system SHALL provide a way to test the connection
2. WHEN testing the connection THEN the system SHALL verify that GitHub API calls can be made successfully
3. WHEN the test is complete THEN the system SHALL report the status and any available tools from the GitHub MCP server

design.md

ちょっとここは```が内部で使われてしまっているのであえて使わずに行こうと思います。

Design Document

Overview

This design outlines the implementation of GitHub MCP server configuration in Kiro workspace. The solution will automatically configure the MCP settings to enable GitHub integration through the Model Context Protocol, allowing users to interact with GitHub repositories, issues, and pull requests directly from Kiro.

Architecture

The GitHub MCP server setup follows Kiro's standard MCP configuration pattern:

.kiro/settings/mcp.json (workspace-level configuration)
├── mcpServers
    └── github
        ├── command: "uvx"
        ├── args: ["@modelcontextprotocol/server-github"]
        ├── env: { GITHUB_PERSONAL_ACCESS_TOKEN, FASTMCP_LOG_LEVEL }
        ├── disabled: false
        └── autoApprove: []

Components and Interfaces

1. MCP Configuration Manager

  • Purpose: Handle reading/writing MCP configuration files
  • Location: Workspace-level .kiro/settings/mcp.json
  • Responsibilities:
    • Create MCP config file if it doesn't exist
    • Update existing configuration without overwriting other servers
    • Validate JSON structure

2. GitHub Authentication Handler

  • Purpose: Manage GitHub Personal Access Token configuration
  • Responsibilities:
    • Prompt user for GitHub PAT if not provided
    • Validate token format and permissions
    • Securely store token in environment configuration

3. Server Connection Validator

  • Purpose: Test GitHub MCP server connectivity and functionality
  • Responsibilities:
    • Attempt to connect to configured GitHub MCP server
    • Verify GitHub API access with provided credentials
    • Report available tools and connection status

Data Models

MCP Configuration Structure

interface MCPConfig {
  mcpServers: {
    [serverName: string]: {
      command: string;
      args: string[];
      env: Record<string, string>;
      disabled: boolean;
      autoApprove: string[];
    }
  }
}

GitHub Server Configuration

interface GitHubMCPServer {
  command: "uvx";
  args: ["@modelcontextprotocol/server-github"];
  env: {
    GITHUB_PERSONAL_ACCESS_TOKEN: string;
    FASTMCP_LOG_LEVEL: "ERROR" | "WARN" | "INFO" | "DEBUG";
  };
  disabled: false;
  autoApprove: string[];
}

Error Handling

Configuration Errors

  • Missing MCP directory: Create .kiro/settings/ directory structure
  • Invalid JSON: Backup existing config and create new valid structure
  • Permission errors: Provide clear error messages about file access

Authentication Errors

  • Invalid GitHub token: Prompt for new token with validation
  • Insufficient permissions: Guide user to create token with required scopes
  • Network connectivity: Provide offline configuration option

Server Connection Errors

  • uvx not installed: Provide installation instructions for uv/uvx
  • Package not found: Verify MCP server package availability
  • Connection timeout: Configure appropriate timeout settings

Testing Strategy

Unit Testing

  • MCP configuration file creation and updates
  • JSON parsing and validation
  • GitHub token format validation

Integration Testing

  • End-to-end GitHub MCP server setup flow
  • Authentication with GitHub API
  • MCP server connection and tool discovery

Manual Testing

  • User workflow testing with different scenarios:
    • Fresh installation (no existing MCP config)
    • Existing MCP config with other servers
    • Invalid/expired GitHub tokens
    • Network connectivity issues

Implementation Approach

Phase 1: Configuration Management

  1. Implement MCP config file handling
  2. Create GitHub server configuration structure
  3. Add basic validation

Phase 2: Authentication Setup

  1. Implement GitHub PAT prompt and validation
  2. Add secure credential storage
  3. Implement token permission verification

Phase 3: Connection Testing

  1. Implement server connectivity testing
  2. Add GitHub API validation
  3. Create status reporting functionality

Phase 4: Error Handling & Polish

  1. Add comprehensive error handling
  2. Implement user-friendly error messages
  3. Add logging and debugging support

task.md

tasks.md
# Implementation Plan

- [ ] 1. Set up MCP configuration management utilities
  - Create functions to read and write MCP configuration files
  - Implement JSON validation and error handling for MCP config structure
  - Add utilities to safely merge new server configurations with existing ones
  - _Requirements: 1.1, 3.2_

- [ ] 2. Implement GitHub MCP server configuration structure
  - Define TypeScript interfaces for GitHub MCP server configuration
  - Create configuration template with proper uvx command and arguments
  - Implement environment variable handling for GitHub authentication
  - _Requirements: 1.1, 2.2, 3.1, 3.2_

- [ ] 3. Create GitHub authentication handling
  - Implement GitHub Personal Access Token prompt and input validation
  - Add token format validation and basic permission checking
  - Create secure storage mechanism for GitHub credentials in MCP config
  - _Requirements: 2.1, 2.2, 2.3_

- [ ] 4. Build MCP configuration file management
  - Implement function to create `.kiro/settings/mcp.json` if it doesn't exist
  - Add logic to update existing MCP configuration without overwriting other servers
  - Create backup mechanism for existing configurations before modifications
  - _Requirements: 1.1, 3.3_

- [ ] 5. Implement GitHub MCP server setup workflow
  - Create main setup function that orchestrates the entire configuration process
  - Integrate authentication handling with MCP configuration creation
  - Add proper error handling and user feedback throughout the setup process
  - _Requirements: 1.1, 1.2, 2.1, 3.3_

- [ ] 6. Add server connection validation
  - Implement function to test GitHub MCP server connectivity
  - Create GitHub API validation using provided credentials
  - Add tool discovery and status reporting functionality
  - _Requirements: 1.3, 4.1, 4.2, 4.3_

- [ ] 7. Create comprehensive error handling
  - Implement specific error handling for missing uvx/uv installation
  - Add validation for GitHub token permissions and scopes
  - Create user-friendly error messages for common configuration issues
  - _Requirements: 2.3, 4.2_

- [ ] 8. Add testing and validation utilities
  - Create unit tests for MCP configuration management functions
  - Implement integration tests for GitHub authentication flow
  - Add end-to-end testing for complete setup workflow
  - _Requirements: 4.1, 4.2, 4.3_

- [ ] 9. Implement user interface and feedback
  - Create clear prompts for GitHub token input and configuration options
  - Add progress indicators and status messages during setup
  - Implement success confirmation and next steps guidance
  - _Requirements: 2.1, 4.3_

- [ ] 10. Finalize and integrate setup command
  - Create main entry point function for GitHub MCP server setup
  - Integrate all components into a cohesive setup workflow
  - Add logging and debugging support for troubleshooting
  - _Requirements: 1.1, 1.2, 1.3, 2.1, 2.2, 2.3, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3_

結果

なぜか、今開いているサービスでmcpを使えるようなものを作っていってしまってます。

image.png

正直、英語なのもあって仕様をちゃんとみてなかったですが、サービスとして使えるようなものを作ろうとしてしまってますね。

Step1の実行だけでこれだけのものができました。

	new file:   .kiro/specs/github-mcp-server-setup/design.md
	new file:   .kiro/specs/github-mcp-server-setup/requirements.md
	new file:   .kiro/specs/github-mcp-server-setup/tasks.md
	new file:   libs/mcp-config/jest.config.ts
	new file:   libs/mcp-config/project.json
	new file:   libs/mcp-config/src/config-manager.spec.ts
	new file:   libs/mcp-config/src/config-manager.ts
	new file:   libs/mcp-config/src/index.ts
	new file:   libs/mcp-config/src/types.ts
	new file:   libs/mcp-config/src/validation.spec.ts
	new file:   libs/mcp-config/src/validation.ts
	new file:   libs/mcp-config/tsconfig.json
	new file:   libs/mcp-config/tsconfig.lib.json
	new file:   libs/mcp-config/tsconfig.spec.json

https://kiro.dev/docs/mcp/configuration/
に書いてあることをやってくれればいいだけだったのに、難しいですね。

ちょっとケースが良くなかったかもですが、メモとして参考になれば。

3
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?