# sysIntd

**Repository Path**: lri_aios/intelligence-d

## Basic Information

- **Project Name**: sysIntd
- **Description**: openEuler IntelligenceD
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: dev-lri
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2025-09-25
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IntelligenceD

A Python-based daemon and client system for managing MCP (Model Context Protocol) servers.

## Overview

IntelligenceD consists of two main components:

- **`sysintd`** - Background daemon that manages services and MCP servers (Entry point: `sys_intd.server.intelligenced:main`)
- **`sysint_ctl`** - Command-line client for interacting with the daemon (Entry point: `sys_intd.client.cli:main`)

The daemon communicates with clients via Unix domain sockets and can be managed through systemd. It uses the [mcp_center](https://gitee.com/zxstty/mcp_center) repository for MCP server definitions and configurations.

## Prerequisites

- [uv](https://github.com/astral-sh/uv) package manager
- systemd (for production installation)
- sudo privileges (for production installation)
- git (for cloning mcp_center)

## Installation

### Production Installation

1. **Install the daemon:**

   ```bash
   sudo make install
   ```

2. **Start the service:**

   ```bash
   sudo systemctl start sysintd
   ```

3. **Enable auto-start on boot:**

   ```bash
   sudo systemctl enable sysintd
   ```

4. **Check service status:**

   ```bash
   sudo systemctl status sysintd
   ```

The installation will:

- Set up mcp_center at `/usr/lib/euler-copilot-framework/mcp_center`
- Install IntelligenceD files to `/opt/sysintd`
- Create command symlinks in `/usr/local/bin`
- Install systemd service file
- Copy configuration to `/etc/sysintd/config`

### Update MCP Center

To update only the mcp_center repository without reinstalling:

```bash
sudo make setup-mcp-prod
```

### Uninstallation

To completely remove IntelligenceD:

```bash
sudo make uninstall
```

This will stop and disable the service, remove all installed files, and clean up symlinks.

## Usage

Once installed, use the `sysint_ctl` command to interact with the daemon:

```bash
# List managed servers
sysint_ctl ls

# Get server information
sysint_ctl info <server-name>

# Start a server
sysint_ctl start <server-name>

# Stop a server
sysint_ctl stop <server-name>

# Search for available servers
sysint_ctl search <query>

# Install a server (shows real-time progress)
sysint_ctl install <server-name>

# Uninstall a server (shows real-time progress)
sysint_ctl uninstall <server-name>

# Create an agent (shows real-time progress)
sysint_ctl agent create --name <agent-name> --mcp_list <server1,server2>
```

### View Logs

Logs are also written to `/var/log/sysintd/sysintd.log` (production) or `./.dev/logs/sysintd.log` (development).

**Log Levels:**
- **Production:** Defaults to `INFO`.
- **Development:** Defaults to `DEBUG` (configured in `.env`).

```bash
# Follow daemon logs
sudo journalctl -u sysintd -f

# View recent logs
sudo journalctl -u sysintd -n 50
```

## Development

### Setup Development Environment

1. **Create development configuration:**

   ```bash
   make env
   ```

   This creates a `.env` file from `.env.template` for local development.

2. **Set up mcp_center for development:**

   ```bash
   make setup-mcp-dev
   ```

   This clones mcp_center to `.dev/mcp_center` in your project root.

3. **Run the daemon in development mode:**

   ```bash
   uv run sysintd
   ```

4. **Run the client in development mode:**

   ```bash
   # Without arguments
   uv run sysint_ctl

   # With arguments
   uv run sysint_ctl ls
   ```

### VS Code Setup

This project includes a `.vscode` configuration to ensure a consistent development environment for all contributors.

1.  **Recommended Extensions**: When you open the project, VS Code will recommend installing the following extensions:
    *   **Python**: For language support.
    *   **Ruff**: For fast linting and formatting.
    *   **Mypy**: For static type checking.

2.  **Automatic Formatting**: The project is configured to automatically format your code with **Ruff** when you save a file.

3.  **Linting**: Ruff will also check for errors and automatically fix common issues on save.

### Debugging in VS Code

1. Open "Run and Debug" panel (`Ctrl+Shift+D`)
2. Use **"Debug Daemon"** configuration to debug the daemon
3. Use **"Debug Client"** configuration to debug the client
   - Ensure the development daemon is running first with `make run-dev-daemon`

### Development vs Production

| Aspect | Development | Production |
|--------|-------------|------------|
| Socket Path | `./.dev/sockets/svc_manager.sock` | `/tmp/svc_manager_hb.sock` |
| Log Path | `./.dev/logs/sysintd.log` | `/var/log/sysintd/sysintd.log` |
| MCP Center | `./.dev/mcp_center` | `/usr/lib/euler-copilot-framework/mcp_center` |
| Installation | Run from source | Installed to `/opt/sysintd` |
| Commands | `make run-dev-*` | `sysintd`, `sysint_ctl` |

### Code Quality

We use `ruff` for linting and formatting. The following commands are available:

```bash
# Check for linting errors
make lint

# Fix auto-fixable linting errors
make lint-fix

# Format code
make format

# Type checking
make type-check
```

### Development Workflow

When contributing to this project, please follow this workflow to ensure code quality:

1. **Write Code**: Implement your feature or fix.
2. **Format**: Run `make format` to ensure your code follows the project's style guide.
3. **Lint**: Run `make lint-fix` to fix common issues, then `make lint` to check for remaining errors.
4. **Type check**: Run `make type-check` to check for typing issues.
5. **Test**: Run `make test` to ensure your changes didn't break existing functionality.
6. **Commit**: Only commit when all checks pass.

## Testing

This project uses `pytest` for testing. We provide a convenient setup for running tests via CLI or VS Code.

### Quick Start

#### Running Tests

You can run tests using `make` commands or directly via VS Code.

**Using Make:**

- Run all tests: `make test`
- Run unit tests only: `make test-unit`
- Run integration tests only: `make test-integration`
- Run tests with coverage: `make test-cov`

**Using VS Code:**

1. Go to the **Testing** tab (beaker icon) in the sidebar.
2. You should see a list of all tests.
3. Click the "Play" button next to any test or folder to run it.
4. Click the "Debug" button (bug with play icon) to debug a test.

#### Writing Tests

- **Unit Tests**: Place in `tests/unit/`. Mirror the source code structure.
  - Example: `sys_intd/manager/mcp_server_manager.py` -> `tests/unit/manager/test_mcp_server_manager.py`
- **Integration Tests**: Place in `tests/integration/`. These test interactions between components.

### Best Practices

1. **Use Fixtures**: We use `pytest` fixtures for setup/teardown. See `tests/conftest.py` for available fixtures like `temp_dir`, `clean_env`, etc.
2. **Mock External Dependencies**: Use `unittest.mock` or `pytest-mock` (`mocker` fixture) to mock file system, network, or system calls.
3. **Keep Tests Independent**: Each test should run in isolation. Do not rely on state from other tests.

### Common Patterns

#### Mocking Configuration

Use the `mock_settings` fixture (in `conftest.py`) to avoid reading real config files.

```python
def test_something(mock_settings):
    # mock_settings.path.local_config_path points to a temp file
    ...
```

#### Mocking the Daemon Socket

The `mock_socket_path` fixture ensures tests don't try to connect to the real running daemon.

```python
def test_connection(mock_socket_path):
    # Socket operations will use the temp socket
    ...
```

### Troubleshooting

- **Tests not discovered in VS Code?**
  - Check the "Output" panel and select "Python" from the dropdown to see errors.
  - Ensure your virtual environment is selected (`.venv`).

- **Import errors?**
  - Make sure you are running tests from the project root.
  - VS Code settings are configured to add the project root to `PYTHONPATH`.

## Configuration

Configuration is managed through:

- **Environment variables:** Prefixed with `SYSINTD_`
- **Settings file:** Defined in `sys_intd/settings/config.py`

Key configuration paths:

- Socket: `/tmp/svc_manager_hb.sock` (production) or configurable via `.env` (development)
- User config: `~/.config/intelligenced/servers.json`
- MCP servers: `~/.config/intelligenced/mcps`
- MCP center: `/usr/lib/euler-copilot-framework/mcp_center` (production) or `./.dev/mcp_center` (development)

## Project Structure

```bash
.
├── Makefile                 # Build and installation commands
├── pyproject.toml          # Project dependencies and metadata
├── scripts/                # Installation and development scripts
│   ├── config.sh           # Shared configuration
│   ├── install.sh          # Production installation
│   ├── uninstall.sh        # Removal script
│   ├── setup-mcp-center.sh # MCP center setup (dev/prod)
│   ├── dev-daemon.sh       # Run daemon in dev mode
│   ├── dev-ctl.sh          # Run client in dev mode
│   └── setup-env.sh        # Setup development environment
├── service/
│   └── sysintd.service     # Systemd service file
└── sys_intd/               # Main Python package
    ├── client/             # Client-side logic (CLI, API, Views)
    ├── server/             # Server-side logic (Daemon, Managers)
    ├── common/             # Shared schemas and utilities
    ├── settings/           # Configuration management
    └── utils/              # Helper utilities
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feat-xxx`)
3. Commit your changes (`git commit -am 'Add feature'`)
4. Push to the branch (`git push origin feat-xxx`)
5. Create a Pull Request

## License

See [LICENSE](LICENSE) file for details.