# MetaAPP MCP Server

A comprehensive MCP (Model Context Protocol) service for MetaAPP development, providing tools for project initialization, protocol exploration, and blockchain interaction.

## Features

- **Project Management**: Initialize, preview, and build MetaApp projects from templates
- **Environment Detection**: Check and guide Node.js and Git installation
- **Protocol Tools**: Query and search MetaID protocols on blockchain
- **Documentation Access**: Built-in MetaID and Metalet wallet API documentation
- **PIN Management**: Fetch and analyze PIN data from blockchain
- **User Information**: Query user profiles by address or MetaID
- **Prompt Templates**: Pre-configured prompts for common MetaApp development tasks

## Installation

### Prerequisites

- Node.js v20.19.1 or higher (recommended via NVM)
- npm or yarn
- Git

### Install Dependencies

```bash
npm install
```

## Development

### Run in Development Mode

```bash
npm run dev
```

### Build the Project

```bash
npm run build
```

### Run Built Version

```bash
npm start
```

## Process Management (PM2)

The server includes PM2 configuration for production deployment with auto-restart capabilities.

### Start with PM2

```bash
npm run pm2:start
```

### Stop PM2 Process

```bash
npm run pm2:stop
```

### Restart PM2 Process

```bash
npm run pm2:restart
```

### View Logs

```bash
npm run pm2:logs
```

## Docker Deployment

### Build Docker Image

```bash
npm run docker:build
# or
docker build -t metaapp-mcp-server .
```

### Run Docker Container

```bash
npm run docker:run
# or
docker run -p 3000:3000 metaapp-mcp-server
```

## MCP Tools

### System Tools

- **get_assistant_metadata**: Get complete server metadata including version and features

### Documentation Tools

- **get_resource_tree**: MetaID and Metalet wallet API documentation
- **get_manv1_api_resource**: MAN V1 API capabilities and endpoints
- **get_manv2_api_resource**: MAN V2 API capabilities and endpoints

### Environment Tools

- **check_environment**: Check if Node.js and Git are installed
- **install_node_guide**: Installation guide for Node.js via NVM
- **install_git_guide**: Installation guide for Git

### Project Tools

- **init_project**: Initialize a new MetaApp project from template
  - Parameters: `project_name`, `project_description`, `target_directory`
- **run_project**: Run npm run dev to preview the project
  - Parameters: `project_path`
- **build_project**: Build and package the project for deployment
  - Parameters: `project_path`

### Protocol Tools

- **get_metaprotocol_list**: Get list of MetaProtocols
  - Parameters: `cursor` (optional), `size` (optional)
- **search_protocol**: Search for a specific protocol by name
  - Parameters: `protocol_name`
- **get_pin_detail**: Get details of a specific PIN
  - Parameters: `pin_id`
- **get_pin_list_by_path**: Get PIN list by protocol path
  - Parameters: `path`, `cursor` (optional), `size` (optional)
- **get_user_info**: Get user information
  - Parameters: `address_or_metaid`

## MCP Prompts

### Available Prompts

1. **meta_app_developer_guide**: Activate professional MetaApp developer mode
2. **init_metaapp_project**: Initialize a new MetaApp project
   - Arguments: `project_name`, `project_description`
3. **explore_protocol**: Explore and understand a MetaID protocol
   - Arguments: `protocol_name`
4. **deploy_metaapp**: Deploy a MetaApp to the blockchain

## Usage Example

### With Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "metaapp": {
      "command": "node",
      "args": ["/path/to/MetaAPP-Mcp/dist/index.js"]
    }
  }
}
```

### Direct Usage

The server runs on stdio transport and communicates via standard input/output:

```bash
node dist/index.js
```

## Project Structure

```
MetaAPP-Mcp/
├── src/
│   ├── config/           # Configuration files
│   ├── prompts/          # Prompt templates
│   ├── tools/            # Tool implementations
│   │   ├── system-tools.ts
│   │   ├── documentation-tools.ts
│   │   ├── project-tools.ts
│   │   └── protocol-tools.ts
│   ├── types/            # TypeScript type definitions
│   ├── utils/            # Utility functions
│   │   ├── helpers.ts
│   │   └── api-client.ts
│   └── index.ts          # Main server entry
├── dist/                 # Compiled JavaScript
├── logs/                 # PM2 logs
├── Dockerfile            # Docker configuration
├── ecosystem.config.cjs  # PM2 configuration
├── tsconfig.json         # TypeScript configuration
└── package.json          # Project metadata

```

## API Endpoints

### MetaID APIs

- **MAN V1**: `https://man.metaid.io/api`
- **MAN V2**: `https://manapi.metaid.io`

### Key Resources

- **MetaID Docs**: https://docs.metaid.io/
- **MetaID SDK**: https://github.com/metaid-developers/metaid-sdk
- **MetaApp Template**: https://github.com/metaid-developers/MetaApp-CLI
- **Metalet Wallet**: https://metalet.space/
- **Deployment**: https://metaweb-world.vercel.app

## Development Workflow

### Creating a New MetaApp

1. **Check Environment**:
   ```
   Use: check_environment
   ```

2. **Initialize Project**:
   ```
   Use: init_project
   Parameters: { target_directory: "/path/to/projects" }
   ```

3. **Explore Protocols**:
   ```
   Use: search_protocol
   Parameters: { protocol_name: "simplenote" }
   ```

4. **Develop Features**: Follow the protocol structure to implement your app

5. **Build for Deployment**:
   ```
   Use: build_project
   Parameters: { project_path: "/path/to/project" }
   ```

6. **Deploy**: Upload the generated zip file to https://metaweb-world.vercel.app

## Troubleshooting

### Node.js Not Found

Use the `install_node_guide` tool to get installation instructions for your platform.

### Git Not Found

Use the `install_git_guide` tool to get installation instructions for your platform.

### Build Errors

Ensure you're in the correct project directory and all dependencies are installed:

```bash
cd your-project
npm install
npm run build
```

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- GitHub Issues: [Create an issue](https://github.com/metaid-developers)
- MetaID Community: https://metaid.io/
- Documentation: https://docs.metaid.io/

## Credits

Built with:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
- [TypeScript](https://www.typescriptlang.org/)
- [Axios](https://axios-http.com/)
- [simple-git](https://github.com/steveukx/git-js)
- [PM2](https://pm2.keymetrics.io/)

---

**MetaAPP MCP Server** - Empowering MetaApp development with AI assistance