intelxlabs-everything/hoashare-mcp-server

HoaShare MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides tools for interacting with accounting and user management services. This server acts as a bridge between AI assistants and HOA (Homeowners Association) management APIs, enabling natural language interactions with financial and user data.

Features

• Multi-Service Integration: Connects to accounting and user management APIs
• Comprehensive Tool Set: 27 tools covering financial operations and user management
• MCP Protocol: Full Model Context Protocol implementation for AI assistant integration
• Type Safety: Complete TypeScript implementation with strict typing
• Error Handling: Robust error handling and logging throughout
• Authentication: Supports Bearer tokens and API key authentication
• Health Monitoring: Built-in health check tools for service monitoring

Tool Categories

Accounting Tools (22 tools)

• Chart of Accounts management
• Bank account operations
• Transaction processing
• Invoice management
• Payment processing

User Management Tools (5 tools)

• User CRUD operations
• Community management
• Unit setup and configuration

Health Check Tools (2 tools)

• Service health monitoring
• API connectivity verification

Prerequisites

Before you begin, ensure you have the following installed:

1. Node.js (v16 or higher) - Download here
2. npm (comes with Node.js) or yarn
3. Access to the accounting and user management APIs
4. Environment variables configured for API endpoints

Getting Started

Follow these steps to set up and run the project:

1. Clone the Repository

If you haven't already, clone the repository to your local machine:

git clone https://github.com/HOA-Share/hoashare-mcp-server
cd hoashare-mcp-server

2. Install Dependencies

Install the required dependencies using npm or yarn:

npm install

or

yarn install

3. Configure Environment Variables

The project uses environment variables to configure API endpoints and authentication. Create a .env file in the root directory or set the following environment variables:

# Accounting API Configuration
ACCOUNTING_API_BASE_URL=your_accounting_api_base_url
ACCOUNTING_BEARER_TOKEN=your_accounting_bearer_token
ACCOUNTING_API_KEY=your_accounting_api_key

# Users API Configuration
USERS_API_BASE_URL=your_users_api_base_url
USERS_BEARER_TOKEN=your_users_bearer_token
USERS_API_KEY=your_users_api_key

Note: You only need to set either the bearer token OR the API key for each service, not both.

4. Build the Project

Compile the TypeScript code into JavaScript:

npm run build

This will generate the compiled files in the dist directory.

5. Run the Server

Start the server in production mode:

npm start

Alternatively, for development mode with live reloading, use:

npm run dev

Testing the Server

1. Using the MCP Inspector

The MCP Inspector is a tool to test and inspect your MCP server. You can use it to verify that your tools are registered correctly.

Run the following command to inspect your server:

npx @modelcontextprotocol/inspector ./dist/index.js

This will open an interactive interface where you can test the 27 tools registered in your server.

Using with AI Assistants

Claude Desktop Setup

1. Build the project first:

   npm run build
   

2. Edit your Claude Desktop configuration:

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

3. Add the MCP server configuration:

   {
     "mcpServers": {
       "hoashare-mcp": {
         "command": "node",
         "args": ["/ABSOLUTE/path/to/hoashare-mcp-server/dist/index.js"],
         "env": {
           "ACCOUNTING_API_BASE_URL": "your_accounting_api_url",
           "ACCOUNTING_BEARER_TOKEN": "your_accounting_token",
           "USERS_API_BASE_URL": "your_users_api_url",
           "USERS_BEARER_TOKEN": "your_users_token"
         }
       }
     }
   }
   

4. Restart Claude Desktop for the changes to take effect.

Cursor IDE Setup

1. Install the MCP extension in Cursor (if available)
2. Configure the server in your workspace settings similar to Claude Desktop
3. Reference the built server at ./dist/index.js

Debugging

View MCP logs:

# View recent MCP logs
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# View all logs
ls ~/Library/Logs/Claude/

Server debugging:

# Run in development mode with detailed logging
npm run dev

# Check server health
curl localhost:3000/health  # if running in HTTP mode

Project Structure

Here's an overview of the project structure:

hoashare-mcp-server/
├── src/
│   ├── index.ts                      # Application entry point
│   ├── server.ts                     # Main MCP server implementation
│   ├── config/
│   │   └── services.ts               # Service configuration
│   ├── services/
│   │   ├── base.ts                   # Base service class
│   │   ├── accounting.ts             # Accounting service implementation
│   │   └── users.ts                  # Users service implementation
│   ├── tools/
│   │   ├── registry.ts               # Tool registry and management
│   │   ├── accounting/
│   │   │   └── definitions.ts        # Accounting tool definitions
│   │   ├── users/
│   │   │   └── definitions.ts        # User tool definitions
│   │   └── health/
│   │       └── definitions.ts        # Health check tool definitions
│   ├── types/
│   │   └── index.ts                  # TypeScript type definitions
│   └── utils/
│       ├── https.ts                  # HTTP client utility
│       └── query-builder.ts          # Query building utility
├── tests/                            # Test files
├── dist/                             # Compiled JavaScript output
├── package.json                      # Project metadata and scripts
├── tsconfig.json                     # TypeScript configuration
└── README.md                         # Project documentation

Troubleshooting

Common Issues

1. Authentication Errors: Verify your API tokens and base URLs are correct
2. TypeScript Errors: Ensure you've installed all dependencies and are using Node.js v16+
3. MCP Connection Issues: Check Claude Desktop logs for connection errors
4. API Connectivity: Test your API endpoints independently before using with MCP

Debugging Steps

1. Check MCP server logs:

   tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
   

2. Test server directly:

   npm run dev
   

3. Inspect with MCP Inspector:

   npx @modelcontextprotocol/inspector ./dist/index.js
   

4. Verify configuration:

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

Available Tools

The server provides 27 tools across three categories:

Accounting Tools

• accounting-get-accounts - Get chart of accounts
• accounting-setup-coa - Setup chart of accounts
• accounting-create-account - Create new account
• accounting-get-account-by-id - Get account details
• accounting-get-banks - Get bank accounts
• accounting-create-bank - Create bank account
• accounting-get-bank-by-id - Get bank details
• accounting-get-transactions - Get transactions
• accounting-create-transaction - Create transaction
• accounting-get-transaction-by-id - Get transaction details
• accounting-get-invoices - Get invoices
• accounting-create-invoice - Create invoice
• accounting-get-invoice-by-id - Get invoice details
• accounting-get-payments - Get payments
• accounting-create-payment - Create payment
• accounting-get-payment-by-id - Get payment details

User Management Tools

• users-get-all - Get all users
• users-get-by-id - Get user by ID
• users-create - Create new user
• users-setup-unit - Setup unit in accounting
• communities-get-all - Get all communities

Health Check Tools

• check-accounting-health - Check accounting service health
• check-users-health - Check users service health

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License. See the file for details.