README.md•5.35 kB
# Kintone Customize Development Support MCP Server
An MCP (Model Context Protocol) server that provides comprehensive development support for kintone customizations, including API specifications, field type documentation, and development tips.
## Features
- 🔍 **API Specification Search**: Query kintone REST API specifications by endpoint, method, or category
- 📝 **Field Types Documentation**: Access detailed information about kintone field types and their properties
- 💡 **Development Tips**: Search development best practices and troubleshooting guides
- ✅ **Request Validation**: Validate API requests against kintone specifications
- 🔄 **Auto-Updates**: Automatic synchronization with official kintone documentation via CICD
## Installation
### Option 1: Install from npm (Recommended)
```bash
# Install globally
npm install -g kntn-dev-mcp
# Or using pnpm
pnpm add -g kntn-dev-mcp
# Or using yarn
yarn global add kntn-dev-mcp
# Run the server
kntn-dev-mcp
```
### Option 2: Install locally in project
```bash
# Install as dependency
npm install kntn-dev-mcp
# Run via npx
npx kntn-dev-mcp
# Or add to package.json scripts
{
"scripts": {
"mcp-server": "kntn-dev-mcp"
}
}
```
### Option 3: Development setup
```bash
# Clone the repository
git clone <repository-url>
cd kntn-dev-mcp
# Install dependencies
pnpm install
# Build the server
pnpm build
# Start the server
pnpm start
```
## MCP Client Configuration
Add the server to your MCP client configuration (e.g., Claude Desktop):
### If installed globally:
```json
{
"mcpServers": {
"kintone-dev-support": {
"command": "kntn-dev-mcp"
}
}
}
```
### If installed locally:
```json
{
"mcpServers": {
"kintone-dev-support": {
"command": "npx",
"args": ["kntn-dev-mcp"]
}
}
}
```
### Development setup:
```json
{
"mcpServers": {
"kintone-dev-support": {
"command": "node",
"args": ["/path/to/kntn-dev-mcp/dist/index.js"]
}
}
}
```
## Available Tools
| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| `search_api_specs` | Search kintone API specifications | `query`, `category`, `method` |
| `search_field_types` | Search field type information | `fieldType`, `category` |
| `search_development_tips` | Find development guidance | `query`, `category`, `difficulty` |
| `get_api_endpoint` | Get detailed endpoint info | `endpoint`, `method` |
| `validate_api_request` | Validate API request format | `endpoint`, `method`, `requestBody` |
| `get_update_info` | Check data update status | `includeHistory` |
## Available Resources
| Resource URI | Description |
|--------------|-------------|
| `kintone://api/specifications` | Complete API specification catalog |
| `kintone://api/field-types` | Field types documentation |
| `kintone://tips/all` | All development tips |
## Usage Examples
### Search API Specifications
```javascript
{
"name": "search_api_specs",
"arguments": {
"query": "get records",
"category": "records"
}
}
```
### Get Field Type Information
```javascript
{
"name": "search_field_types",
"arguments": {
"fieldType": "SINGLE_LINE_TEXT",
"includeProperties": true
}
}
```
### Find Development Tips
```javascript
{
"name": "search_development_tips",
"arguments": {
"query": "performance optimization",
"category": "performance"
}
}
```
## Development
### Scripts
- `pnpm build` - Build TypeScript to JavaScript
- `pnpm test` - Run all tests
- `pnpm test:watch` - Run tests in watch mode
- `pnpm lint` - Run Biome linter
- `pnpm format` - Format code with Biome
### Project Structure
```
src/
├── models/ # Data models and interfaces
├── server/ # MCP server core functionality
├── tools/ # Individual tool implementations
├── services/ # Storage and update services
└── index.ts # Application entry point
tests/
├── contract/ # MCP protocol compliance tests
├── tools/ # Individual tool tests
├── integration/ # End-to-end scenario tests
├── unit/ # Unit tests
└── performance/ # Performance tests
```
### Testing
The project follows Test-Driven Development (TDD):
1. **Contract Tests**: Verify MCP protocol compliance
2. **Tool Tests**: Test individual tool functionality
3. **Integration Tests**: End-to-end user scenarios
4. **Unit Tests**: Component-level testing
## Architecture
- **TypeScript**: Type-safe development with strict mode
- **MCP SDK**: Official Model Context Protocol implementation
- **File Storage**: JSON-based data storage for specifications
- **CICD Integration**: Automatic updates from official kintone sources
- **Vitest**: Fast unit testing framework
- **Biome**: Fast linting and formatting
## Data Sources
The server automatically synchronizes with official kintone resources:
- **API Specifications**: https://github.com/kintone/rest-api-spec
- **Field Types**: https://cybozu.dev/ja/kintone/docs/overview/field-types/
- **Development Tips**: https://cybozu.dev/ja/kintone/tips/development/
## Contributing
1. Follow the existing TDD workflow
2. All tests must pass before committing
3. Use Biome for code formatting
4. Update documentation for new features
## License
[MIT](./LICENSE)